@ariadnejs/mcp

Model Context Protocol server for Ariadne - Give AI coding assistants powerful code intelligence capabilities.

Overview

This package provides an MCP (Model Context Protocol) server that exposes Ariadne's code intelligence features to AI assistants like Claude, Cursor, Continue, and other MCP-compatible tools. It enables AI agents to understand your codebase deeply by analyzing code structure, finding definitions and references, tracking inheritance relationships, and understanding function call graphs.

Key Benefits

• Deep Code Understanding: AI can navigate your codebase like an experienced developer
• Accurate Symbol Resolution: Find exact definitions and usages across files
• Context-Aware Assistance: AI understands inheritance, implementations, and call relationships
• Multi-Language Support: Works with JavaScript, TypeScript, Python, and Rust

Installation

Global Installation (Recommended)

npm install -g @ariadnejs/mcp

Project-Specific Installation

npm install --save-dev @ariadnejs/mcp

Quick Start

Step 1: Install the MCP Server

npm install -g @ariadnejs/mcp

Step 2: Configure Your AI Assistant

Claude Desktop

Add to your claude_desktop_config.json (usually in ~/Library/Application Support/Claude/ on macOS):

{
  "mcpServers": {
    "ariadne": {
      "command": "npx",
      "args": ["@ariadnejs/mcp"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project"
      }
    }
  }
}

Cursor

Add to your .cursor/mcp/config.json in your project root:

{
  "servers": {
    "ariadne": {
      "command": "npx",
      "args": ["@ariadnejs/mcp"]
    }
  }
}

Continue

Add to your ~/.continue/config.json:

{
  "models": [...],
  "mcpServers": {
    "ariadne": {
      "command": "npx",
      "args": ["@ariadnejs/mcp"]
    }
  }
}

For more detailed setup instructions, see the Setup Guide.

Usage

Running the MCP Server

npx ariadne-mcp

Or programmatically:

import { startServer } from '@ariadnejs/mcp';

startServer({
  projectPath: './my-project'
});

Available Tool

The MCP server currently provides one powerful context-oriented tool:

get_symbol_context

Get comprehensive information about any symbol by name - no file position needed!

// Example usage by AI:
{
  "tool": "get_symbol_context",
  "arguments": {
    "symbol": "processPayment",
    "includeTests": true
  }
}

Parameters:

• symbol (required): Name of the function, class, or variable to look up
• searchScope (optional): "file" | "project" | "dependencies" (default: "project")
• includeTests (optional): Whether to include test file references (default: false)

Returns:

• Full function/class implementation with documentation
• Usage statistics (references, imports, tests)
• Call relationships (calls/called by)
• Class inheritance and interface implementations
• File location and signature

Coming soon:

• get_call_graph - Analyze function call relationships
• get_references - Find all references to a symbol
• preview_refactor - Preview the impact of refactoring changes

Example Use Cases

For AI Assistants

Once configured, AI assistants can help you with:

• Code Navigation: "Show me the implementation of the authenticate function"
• Impact Analysis: "What functions would be affected if I change the User class?"
• Code Understanding: "Explain how the PaymentService interacts with other services"
• Refactoring: "Find all places where the deprecated processOrder function is used"
• Architecture Review: "Show me the call graph starting from the main API endpoints"
• Test Coverage: "Which functions in the auth module don't have tests?"

For Developers

The MCP server helps AI assistants provide better:

• Code Reviews: Understanding the full context of changes
• Bug Investigation: Tracing function calls and data flow
• Documentation: Generating accurate docs based on actual code structure
• Refactoring Suggestions: Safe rename and move operations
• Architecture Decisions: Understanding existing patterns and dependencies

Configuration

Environment Variables

• PROJECT_PATH: The root directory of your project (defaults to current working directory)
• LOG_LEVEL: Logging verbosity (debug, info, warn, error)

Project-Specific Configuration

{
  "mcpServers": {
    "ariadne": {
      "command": "npx",
      "args": ["@ariadnejs/mcp"],
      "env": {
        "PROJECT_PATH": "/path/to/your/project",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Supported Languages

• ✅ JavaScript (including JSX)
• ✅ TypeScript (including TSX)
• ✅ Python
• ✅ Rust
• 🚧 More languages coming soon (Go, Java, C/C++, etc.)

Version Compatibility

This package requires:

• @ariadnejs/core >= 0.5.15
• @ariadnejs/types >= 0.5.15

The MCP package versions independently from core packages. Check the releases page for compatibility information.

Troubleshooting

Common Issues

MCP server not connecting

• Check that @ariadnejs/mcp is installed globally: npm list -g @ariadnejs/mcp
• Verify your AI assistant's config file syntax is correct
• Restart your AI assistant after configuration changes

"Symbol not found" errors

• Ensure PROJECT_PATH points to your project root
• Check that your project files are saved
• Verify the language is supported (JS/TS/Python/Rust)

Performance issues

• Large codebases may take time for initial indexing
• Exclude node_modules and build directories if possible
• Consider using project-specific installation for better caching

Debug Mode

Enable debug logging to troubleshoot issues:

{
  "env": {
    "LOG_LEVEL": "debug"
  }
}

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Start development server
npm start

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

ISC