Codebase Knowledge Agent

A self-initializing codebase knowledge agent that provides semantic code search, proactive technology research, dependency intelligence, and intelligent context generation for Claude Code and Cursor.

Features

• Semantic Code Search: Find code by meaning, not just keywords
• Proactive Technology Research: Research technologies before adding them to your project
• Dependency Intelligence: Automatic research and best practices for dependencies
• Intelligent Context: Context-aware assistance based on your current work
• Octocode Integration: Search packages and GitHub code via Octocode MCP

Architecture

Claude Code → MCP Server (stdio) → Backend Server (HTTP) → MongoDB/Tavily/Voyage/Octocode

Two-service architecture:

• MCP Server: Lightweight wrapper that handles MCP protocol
• Backend Server: Business logic, MongoDB operations, research engine

Prerequisites

• Node.js 20.19.0+ (or 22.12.0+ if using v22, or any v23+)
• MongoDB Atlas cluster (for vector search)
• Tavily API key
• Voyage AI API key
• Octocode MCP server (optional)

Quick Start

Install via NPM

npm install -g codebase-knowledge-agent

Or use with npx (no installation needed):

npx codebase-knowledge-agent@latest

Install from Source

1. Clone the repository:

git clone <repository-url>
cd codebase-knowledge-agent

2. Install dependencies:

npm install

3. Build the project:

npm run build

Configuration

Create a .env file in the root directory (see .env.example for all options):

# Required: MongoDB, Voyage AI, Tavily
MONGODB_URI=mongodb+srv://username:[email protected]/database
VOYAGE_API_KEY=your-voyage-api-key
TAVILY_API_KEY=your-tavily-api-key

# Optional: Server Configuration
BACKEND_PORT=8181
PROJECT_PATH=/path/to/your/project
LOG_LEVEL=INFO

# Production: CORS Configuration
CORS_ORIGIN=https://app.example.com

# Optional: Tavily Polling Timeout
TAVILY_POLLING_TIMEOUT=30

Environment Variables

Required:

• MONGODB_URI - MongoDB Atlas connection string
• VOYAGE_API_KEY - Voyage AI API key for embeddings
• TAVILY_API_KEY - Tavily API key for research

Optional:

• BACKEND_PORT - Backend server port (default: 8181)
• BACKEND_URL - Backend URL for MCP server (default: http://localhost:8181)
• PROJECT_PATH - Path to project to index (default: current directory)
• CORS_ORIGIN - Comma-separated allowed origins for production
• TAVILY_POLLING_TIMEOUT - Research API polling timeout in seconds (default: 30)
• LOG_LEVEL - Logging level: DEBUG, INFO, WARN, ERROR (default: INFO)
• NODE_ENV - Set to "production" for production deployment
• OCTOCODE_MCP_COMMAND - Octocode MCP command (default: npx)
• OCTOCODE_MCP_ARGS - Octocode MCP arguments (default: -y @octocode/mcp-server)

Usage

Development

Start both servers in development mode:

npm run dev

Or start them separately:

# Terminal 1: Backend server
npm run dev:backend

# Terminal 2: MCP server
npm run dev:mcp

Production

Build and start:

npm run build
npm run start:backend
npm run start:mcp

Claude Code Configuration

Option 1: NPM Installation (Recommended)

Install via NPM and configure:

{
  "mcpServers": {
    "codebase-knowledge": {
      "command": "npx",
      "args": ["codebase-knowledge-agent@latest"],
      "env": {
        "BACKEND_URL": "http://localhost:8181",
        "MONGODB_URI": "mongodb+srv://username:[email protected]/database",
        "VOYAGE_API_KEY": "your-voyage-api-key",
        "TAVILY_API_KEY": "your-tavily-api-key"
      }
    }
  }
}

Configuration File Locations:

• Claude Code: ~/.config/claude-code/claude_desktop_config.json (verify path)
• Cursor: ~/.cursor/mcp.json or .cursor/mcp.json in project root
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

Option 2: Local Installation

If installed locally or from source:

{
  "mcpServers": {
    "codebase-knowledge": {
      "command": "node",
      "args": ["/path/to/codebase-knowledge-agent/dist/mcp-server/index.js"],
      "env": {
        "BACKEND_URL": "http://localhost:8181",
        "MONGODB_URI": "mongodb+srv://...",
        "VOYAGE_API_KEY": "...",
        "TAVILY_API_KEY": "..."
      }
    }
  }
}

Backend Server Setup

Important: The backend server must be running before using the MCP server.

Start the backend server:

# After installing the package
npm run start:backend

# Or if installed globally
codebase-knowledge-agent-backend  # (if we add this command)

The backend server runs on port 8181 by default (configurable via BACKEND_PORT environment variable).

Available Tools

semantic_code_search

Search your codebase by meaning. Finds semantically similar code.

Example: "authentication middleware" → finds all auth-related code

research_technology

Research a technology before adding it. Provides best practices, patterns, and implementation guidance.

Example: Research "Redis" for "caching" → comprehensive research report

get_intelligent_context

Get intelligent context for your current work. Provides related code and dependency knowledge.

Example: Working on a file → gets semantically similar code + best practices

research_dependency

Research a dependency that's already in your project.

Example: Research "mongoose" → best practices and patterns

octocode_search_package

Search for npm/Python/Go packages via Octocode.

octocode_search_code

Search GitHub code via Octocode.

octocode_get_file

Get file content from GitHub via Octocode.

MongoDB Setup

Vector Search Index

Create a vector search index in MongoDB Atlas:

1. Go to Atlas → Search → Create Search Index
2. Choose "JSON Editor"
3. Create index on code_index collection:

{
  "fields": [
    {
      "type": "vector",
      "path": "embedding",
      "numDimensions": 1024,
      "similarity": "cosine"
    }
  ]
}

Development

Project Structure

codebase-knowledge-agent/
├── src/
│   ├── mcp-server/       # MCP protocol layer
│   ├── backend-server/    # Business logic server
│   ├── agent/            # Agent initialization and orchestration
│   ├── services/         # External service clients
│   ├── tools/            # MCP tool handlers
│   ├── prompts/          # Prompt engineering
│   └── types/            # TypeScript types
├── references/           # Reference repositories (gitignored)
└── tests/               # Tests

Testing

npm test

Linting

npm run lint

Troubleshooting

MongoDB Connection Issues

• Verify MONGODB_URI is correct
• Check network access in Atlas
• Ensure IP is whitelisted

Vector Search Not Working

• Verify vector search index is created in Atlas
• Check index name matches "vector_index"
• Ensure embeddings are 1024 dimensions

Tavily API Errors

• Verify TAVILY_API_KEY is correct
• Check API rate limits
• Verify network connectivity

Voyage AI Errors

• Verify VOYAGE_API_KEY is correct
• Check API quota
• Ensure model names are correct

License

MIT