Skip to content

MCP_QUICKSTART.md

Latest commit

 

History

History
219 lines (153 loc) · 5.25 KB

MCP_QUICKSTART.md

File metadata and controls

219 lines (153 loc) · 5.25 KB
Raw

K0ntext - MCP Server Quick Start

Connect the K0ntext MCP server to Claude Desktop (or other MCP-compatible AI assistants) to give your AI intelligent access to your codebase.

What is MCP?

The Model Context Protocol (MCP) is a standard for AI assistants to access external tools and data. With K0ntext's MCP server, your AI can:

  • Search your codebase semantically
  • Retrieve specific files and context
  • Query the knowledge graph
  • Run intelligent analysis
  • Check documentation drift

Prerequisites

  1. K0ntext installed:

    npm install -g k0ntext

  2. Claude Desktop (or another MCP-compatible client)

  3. A project initialized with K0ntext:

    cd your-project
k0ntext init

Setup with Claude Desktop

Step 1: Find Your Claude Config

The config location depends on your OS:

Platform Config Path
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json

Step 2: Add K0ntext MCP Server

Edit your claude_desktop_config.json:

{
  "mcpServers": {
    "k0ntext": {
      "command": "npx",
      "args": [
        "-y",
        "k0ntext",
        "mcp"
      ],
      "cwd": "/path/to/your/project"
    }
  }
}

Important: Replace /path/to/your/project with your actual project path.

Multiple Projects

For multiple projects, use different server names:

{
  "mcpServers": {
    "k0ntext-project-a": {
      "command": "npx",
      "args": ["-y", "k0ntext", "mcp"],
      "cwd": "/path/to/project-a"
    },
    "k0ntext-project-b": {
      "command": "npx",
      "args": ["-y", "k0ntext", "mcp"],
      "cwd": "/path/to/project-b"
    }
  }
}

Step 3: Restart Claude Desktop

Completely quit and restart Claude Desktop.

Step 4: Verify Connection

In a new Claude conversation, you should see k0ntext listed in the available MCP tools.

Available MCP Tools

The K0ntext MCP server provides these tools:

Tool Description
search_context Semantic search across indexed content
get_item Retrieve specific context items by ID
add_knowledge Store insights and facts
analyze Run intelligent codebase analysis
get_tool_configs View AI tool configurations
query_graph Traverse knowledge graph
get_stats Database statistics
add_relation Add relationships between items
find_path Find paths between items
run_drift_check Check documentation sync

Usage Examples

Semantic Search

Ask Claude:

"Search my codebase for how authentication is implemented"

Claude will use search_context to find relevant code.

Get Specific Item

Ask Claude:

"Get the item with ID abc123"

Add Knowledge

Ask Claude:

"Add to my knowledge base: The authentication system uses JWT tokens with a 1-hour expiration"

Run Analysis

Ask Claude:

"Run an intelligent analysis of my codebase"

Troubleshooting

MCP Server Not Appearing

  1. Check config path: Ensure you're editing the correct config file
  2. Restart Claude: Completely quit and restart Claude Desktop
  3. Check project path: Verify cwd points to a valid project with .k0ntext.db
  4. Check logs: Look for MCP errors in Claude's developer console

Database Not Found

Error: Database file not found: .k0ntext.db

Solution: Run k0ntext init in your project directory first.

OpenRouter API Key Missing

If using intelligent analysis:

Error: OPENROUTER_API_KEY not set

Solution: Set your API key:

export OPENROUTER_API_KEY="your-key-here"

Or add to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Port Already in Use

Error: Port 3000 already in use

Solution: The MCP server uses stdio (not HTTP), so this shouldn't occur. If it does, ensure no other MCP servers are configured with the same name.

Advanced Configuration

Custom Server Port (Future)

The current MCP server uses stdio transport. HTTP/SSE transport may be added in the future.

Environment Variables

Available environment variables for the MCP server:

# Database location
export K0NTEXT_DB_PATH="/custom/path/.k0ntext.db"

# OpenRouter API key (for intelligent analysis)
export OPENROUTER_API_KEY="your-key-here"

# Log level
export K0NTEXT_LOG_LEVEL="debug"  # debug, info, warn, error

MCP Prompts

K0ntext also provides 6 prompts for Claude:

Prompt Description
analyze-codebase Analyze the entire codebase
find-similar-code Find code similar to a pattern
explain-architecture Explain system architecture
review-changes Review recent code changes
suggest-improvements Suggest code improvements
check-drift Check documentation drift

These prompts can be invoked directly from Claude Desktop.

Next Steps

Support