npm package: @ravell-io/mcp
Description: MCP server for Ravell's knowledge graph
Latest version: 0.2.1

# @ravell-io/mcp

MCP server that gives AI agents access to Ravell's knowledge graph.

## What it does

Ravell connects your product tools (Linear, Slack, Intercom, Attio, Notion) and builds a unified knowledge graph — resolving cross-source identities, indexing documents, and linking entities. This MCP server exposes that graph to any MCP-compatible AI client, letting agents search your product data, traverse relationships, and run synthesis queries without leaving the conversation.

## Tools

| Tool | Description | Tier |
|------|-------------|------|
| `ravell_search` | Find documents across connected sources. Returns ranked results with relevance scores and entity annotations. | Retrieval |
| `ravell_entities` | Look up people, companies, and teams. Resolves cross-source identities (Linear user, Slack handle, Intercom contact). | Retrieval |
| `ravell_related` | Traverse the graph from a known document or entity to find connected items. | Retrieval |
| `ravell_query` | Natural language question → synthesized answer with citations. Runs the full agent pipeline. Takes 15–45 seconds. | Synthesis |
| `ravell_digest` | Periodic intelligence digest: top problems, emerging blind spots, graph health metrics. | Intelligence |
| `ravell_problems` | Ranked product problems scored by evidence, confidence, recency, and source diversity. | Intelligence |
| `ravell_emerging_issues` | Rising problems that nobody has responded to yet. | Intelligence |
| `ravell_customer_problems` | Find problems affecting a specific customer or company. | Intelligence |
| `ravell_weekly_delta` | What changed in product intelligence since last week. | Intelligence |
| `ravell_for_me` | Personalized "what should I know today?" — top problems, emerging issues, graph health. | Intelligence |
| `ravell_explain` | Evidence trail for a specific entity: relationships, source documents, and citations. | Intelligence |
| `ravell_graph_health` | Product graph health metrics: entity counts, assertion rates, staleness. | Intelligence |

## Quick Start

### 1. Setup (recommended)

The setup command handles everything — authentication, Claude Code skill installation, and MCP configuration:

```bash
npx @ravell-io/mcp setup
```

This will:
1. Open your browser to authenticate with your Ravell workspace
2. Save credentials to `~/.ravell/credentials.json` (not in your project files)
3. Install the bundled Claude Code skill to `~/.claude/skills/ravell/`
4. Add the MCP server to your project's `.mcp.json`

Restart Claude Code after setup to activate.

### 2. Manual setup (alternative)

If you prefer to configure manually:

**Generate an API key** in your Ravell workspace: Settings → API Keys → Create.

**Add to `.mcp.json`** (project-level or `~/.mcp.json` for global):

```json
{
  "mcpServers": {
    "ravell": {
      "command": "npx",
      "args": ["-y", "@ravell/mcp"],
      "env": {
        "RAVELL_API_KEY": "ravelk_your_api_key_here"
      }
    }
  }
}
```

## CLI Commands

```bash
npx @ravell-io/mcp setup     # Full setup: auth + skills + config
npx @ravell-io/mcp login     # Authenticate only
npx @ravell-io/mcp logout    # Remove saved credentials
npx @ravell-io/mcp status    # Show authentication status
```

## Authentication

Credentials are resolved in this order:

1. `RAVELL_API_KEY` environment variable (highest priority, backward compatible)
2. `~/.ravell/credentials.json` (saved by `setup` / `login`)

If neither is found, tools return an error asking the user to run `npx @ravell-io/mcp setup`.

## Bundled Skill

The package includes a Claude Code skill at `skills/ravell/SKILL.md` that auto-triggers when you ask product data questions. It guides Claude to pick the right Ravell tool:

- "Find issues about X" → `ravell_search`
- "Who is X?" → `ravell_entities`
- "What are the top complaints?" → `ravell_query`
- "What happened this week?" → `ravell_digest`

The skill is installed automatically by `npx @ravell-io/mcp setup`.

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `RAVELL_API_KEY` | No* | — | API key (overrides credential file) |
| `RAVELL_API_URL` | No | `https://api.ravell.io` | API base URL |
| `RAVELL_APP_URL` | No | `https://app.ravell.io` | Web app URL (for login flow) |

\* Not required if authenticated via `npx @ravell-io/mcp setup`.

## Development

```bash
npm install          # Install dependencies
npm run build        # Build to dist/
npm run dev          # Watch mode
npm start            # Run the MCP server
```

For local development, point `.mcp.json` to the built output:

```json
{
  "mcpServers": {
    "ravell": {
      "command": "node",
      "args": ["/path/to/ravell-mcp/dist/index.js"]
    }
  }
}
```

Test with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## Tool Reference

### `ravell_search`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Natural language search query (max 1000 chars) |
| `source_types` | string[] | No | Filter: `linear`, `slack`, `intercom`, `attio`, `notion` |
| `team_ids` | string[] | No | Filter by team IDs |
| `date_from` | string | No | Start date (YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY-MM-DD) |
| `limit` | number | No | Max results, 1–50 (default: 10) |

### `ravell_entities`

Provide either `query` or `entity_id` — at least one is required.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | No | Search by name or alias |
| `entity_id` | number | No | Direct lookup by entity ID |
| `relationship_types` | string[] | No | Filter relationships by type |

### `ravell_related`

Provide either `document_id` or `entity_id` — at least one is required.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `document_id` | string | No | UUID of the source document |
| `entity_id` | number | No | ID of the source entity |
| `source_types` | string[] | No | Filter results to specific sources |

### `ravell_query`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `question` | string | Yes | Question about your product data (max 2000 chars) |
| `source_types` | string[] | No | Restrict retrieval to specific sources |
| `date_from` | string | No | Start date (YYYY-MM-DD) |
| `date_to` | string | No | End date (YYYY-MM-DD) |

### `ravell_digest`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `period` | string | Yes | `today`, `this_week`, or `last_7_days` |
| `focus` | string | No | `bugs`, `feature_requests`, `sentiment`, or `all` (default: `all`) |

### `ravell_for_me`

No parameters. Returns a personalized summary of top problems, emerging issues, and graph health.

### `ravell_explain`

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `entity_id` | number | Yes | ID of the entity to explain |

## Architecture

Thin TypeScript adapter built on the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk). Exposes tools via MCP over stdio, translates tool arguments into HTTP requests to the Ravell API (`/api/knowledge/*`), and returns JSON responses as MCP text content. No local state, caching, or business logic — all intelligence lives in the Rails backend.