@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:

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):

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

CLI Commands

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

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:

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

Test with the MCP Inspector:

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. 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.