Skip to main content
Glama
Stokesy-dev

MCP Codebase Context Server

by Stokesy-dev
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

MCP Codebase Context Server

A self-hosted MCP (Model Context Protocol) server that gives LLMs intelligent, semantic access to your codebase — instead of dumping raw files, it lets agents query code the way a senior engineer would.

CI

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client (Claude Code)                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP/SSE (MCP protocol)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Caddy (TLS + reverse proxy)                  │
│     /mcp → mcp-server:8000   /agent → langgraph-agent:8001     │
└───────────┬─────────────────────────────┬───────────────────────┘
            │                             │
            ▼                             ▼
┌───────────────────┐         ┌───────────────────────────────────┐
│   MCP Server      │         │   LangGraph Agent Service         │
│   (port 8000)     │         │   (port 8001)                     │
│                   │         │                                   │
│ Tools:            │         │  POST /invoke                     │
│  search_codebase  │◄────────│  ┌─────────────────────────────┐ │
│  get_recent_changes         │  │ router_node (ChatGroq)       │ │
│  explain_function │         │  │      ↓ (conditional)        │ │
└─────────┬─────────┘         │  │ tool_executor_node          │ │
          │                   │  │      ↓ (loop back)          │ │
          ▼                   │  │ synthesizer_node            │ │
┌─────────────────────────────┤  └─────────────────────────────┘ │
│         Retrieval Pipeline  │                                   │
│                             └───────────────────────────────────┘
│  PythonChunker (ast)
│      ↓
│  Embedder (unixcoder-base)
│      ↓
│  RepoIndex (FAISS IndexFlatIP) ──── persisted to data/
│      ↓
│  HybridRanker
│    • w1 × semantic_score
│    • w2 × recency_score  (exp(-λ × days_since_commit))
│    • w3 × file_relevance (1 / (1 + import_graph_distance))
│      ↓
│  ImportGraph (networkx DiGraph)
│  GitIntegration (GitPython)
└─────────────────────────────────────────────────────────────────

Free stack: Oracle Cloud Always Free (Ampere A1, 4 OCPU / 24GB), Groq free API tier (llama-3.3-70b-versatile), no paid dependencies.

Related MCP server: code-rag

Prerequisites

  • Python 3.11+

  • uv (install: curl -LsSf https://astral.sh/uv/install.sh | sh)

  • Git

  • Docker + Docker Compose (for deployment)

  • A Groq API key (free, no credit card required)

Quick Start (Local)

1. Clone and install

git clone https://github.com/your-username/mcp-codebase-server.git
cd mcp-codebase-server
uv sync --all-extras --dev

2. Configure

cp .env.example .env
# Edit .env — set GROQ_API_KEY and MCP_API_KEY

Edit repos.yaml to point at your local repositories:

repos:
  - name: "my-project"
    path: "/absolute/path/to/your/repo"
    branch: "main"

Optionally tune config.yaml (ranking weights, model, etc.).

3. Run the MCP server

uv run uvicorn src.server.app:app --port 8000 --reload

4. Run the LangGraph agent

uv run uvicorn src.orchestration.agent_app:app --port 8001 --reload

5. Run tests

uv run pytest --cov=src -v

Connecting Claude Code

Add to your Claude Code MCP config (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "codebase": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-API-Key": "your-mcp-api-key"
      }
    }
  }
}

Docker (Local or Cloud)

# Build and start all services
docker compose up --build -d

# Check health
curl http://localhost:8000/health
curl http://localhost:8001/health

# Tail logs
docker compose logs -f

Example Queries

Via MCP tools (Claude Code)

search_codebase("JWT authentication token validation")
get_recent_changes("src/auth/", "my-project", limit=5)
explain_function("process_payment", "src/payments/processor.py", "my-project")

Via LangGraph agent (HTTP)

curl -X POST http://localhost:8001/invoke \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does the authentication flow work and what changed recently?",
    "repo_names": ["my-project"],
    "anchor_files": ["src/auth/middleware.py"]
  }'

The agent will autonomously call search_codebase, then get_recent_changes, then synthesize a final answer.

Configuration Reference

repos.yaml

Field

Required

Description

name

✅

Unique identifier for the repo

path

✅

Absolute path to the repo root

branch

❌

Branch to index (default: current HEAD)

config.yaml

Field

Default

Description

retrieval.w1_semantic

0.6

Weight for semantic similarity

retrieval.w2_recency

0.2

Weight for commit recency

retrieval.w3_file_relevance

0.2

Weight for import graph proximity

retrieval.recency_lambda

0.05

Decay constant λ (days)

retrieval.default_k

10

Default search result count

retrieval.embedding_model

microsoft/unixcoder-base

Sentence-transformers model

retrieval.data_dir

data

Directory for persisted indexes

orchestration.max_iterations

5

Max LangGraph tool-call iterations

orchestration.groq_model

llama-3.3-70b-versatile

Groq model for routing/synthesis

.env

Variable

Description

MCP_API_KEY

API key required in X-API-Key header

GROQ_API_KEY

Groq API key for LangGraph LLM

LOG_LEVEL

DEBUG, INFO, WARNING, ERROR

Design Decisions

Decision

Rationale

AST chunking over line-based

Function/class boundaries are the natural unit engineers reason about

Three ranking signals

Semantic alone misses temporal relevance; recency + file proximity approximate how a senior engineer prioritises

Groq over Ollama

Oracle free VM has 24GB RAM; offloading LLM compute to Groq keeps the VM dedicated to embedding/retrieval

unixcoder-base embeddings

Pre-trained on CodeSearchNet — meaningfully represents identifiers and API names

Import graph file relevance

Static AST import parsing; neutral score (0.5) for unresolvable imports

Deployment

See docs/deployment.md for the full Oracle Cloud setup guide.

License

MIT

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Stokesy-dev/mcp-codebase-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server