This MCP server gives LLMs persistent, searchable access to project context—load full context, semantically search past decisions, save session notes, re-index documentation, and list repositories.
Load project context: Retrieve project overview, all ADRs, and the latest session summary for a given project path (filesystem, owner/repo, or full URL).
Semantically search context: Use natural language queries to find relevant past decisions, architecture notes, or code summaries from the indexed vector store.
Save session summaries: Append a concise Markdown summary of the session to .context/sessions/YYYY-MM-DD.md.
Re-index the context: Refresh the vector store after updating project.md, adding ADRs, or changing BUNDLE.md so searches reflect the latest content.
List repositories: Enumerate available repositories, optionally filtered by organization name, to discover which projects can be accessed.
Configuration flexibility: Supports multiple embedding providers (Ollama, Voyage AI, OpenAI, Cohere, Gemini, Vertex AI), vector stores (ChromaDB local/HTTP, pgvector), repository providers (local, GitHub, GitLab, Gitea), and transports (stdio or SSE with optional auth) to fit various deployment environments.
Integrates with VS Code Copilot to provide access to project context such as documentation and architecture decisions.
Supports JetBrains IDEs through the Continue extension, giving the assistant access to project context.
Uses Ollama as the embedding model provider for semantic search over project documentation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-project-context-server find documentation about authentication flow"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Project Context Server provides a robust, production-ready Model Context Protocol (MCP) server implementation designed to give Large Language Models (LLMs) persistent, searchable access to your project's contextual information.
🔍 Semantic Search Engine: Query your project documentation using natural language
📚 Persistent Knowledge Base: Store and retrieve information from .context/ directory structure
🏗️ Modular Architecture: Pluggable embedding providers, vector stores, and repository providers
🎯 ADR Integration: Full support for Architecture Decision Records with lifecycle management
📝 Session Tracking: Record and retrieve session notes for future reference
🔄 Easy Reindexing: Rebuild your knowledge base with a single command
✅ Multi-Provider Embedding: Ollama, Voyage AI, OpenAI, Cohere, Google Gemini, and Google Vertex AI
✅ Flexible Vector Storage: ChromaDB (local or HTTP) and pgvector (PostgreSQL)
✅ Multiple Repository Providers: Local filesystem, GitHub, GitLab, and Gitea
✅ Transport Options: stdio (default) and HTTP/SSE for remote deployments
✅ Configuration-Free: Environment variable-based setup, no hardcoded paths
✅ Cross-Platform: Works on Windows, macOS, and Linux
✅ Async-First: All operations use async/await for performance and scalability
✅ Error-Resilient: Graceful error handling with informative messaging
Related MCP server: context-hub-mcp
Before installing, ensure you have:
Python 3.11+ installed
Ollama running with an embedding model (e.g., nomic-embed-text)
At least 2GB RAM available
4.5GB disk space for ChromaDB (minimum)
pip install mcp-project-context-serverThe core package contains the server, tools, and ChromaDB local integration. It does not bundle any embedding provider SDK. You must install the extra for your chosen provider.
Install the extra that matches your chosen embedding provider:
Provider | Extra | Install Command |
Ollama (local, no API key) |
|
|
Voyage AI |
|
|
OpenAI |
|
|
Cohere |
|
|
Google Gemini |
|
|
Google Vertex AI |
|
|
ChromaDB (local and HTTP) is included in the core package. Install the pgvector extra only if you are using PostgreSQL:
pip install "mcp-project-context-server[pgvector]"Required only when running the server over HTTP/SSE (remote deployments, Google Agent Engine, etc.):
pip install "mcp-project-context-server[sse]"Multiple extras can be combined in a single install:
# Ollama with pgvector
pip install "mcp-project-context-server[ollama,pgvector]"
# OpenAI with SSE transport
pip install "mcp-project-context-server[openai,sse]"
# Cohere with pgvector and SSE
pip install "mcp-project-context-server[cohere,pgvector,sse]"pip install "mcp-project-context-server[all]"git clone https://github.com/DarkMatterProductions/mcp-project-context-server.git
cd mcp-project-context-server
pip install -e ".[ollama]" # Replace with your chosen provider extraThe embedding provider is selected by the EMBED_PROVIDER environment variable. This variable is required — the server will not start without it.
export EMBED_PROVIDER=ollama # Replace with your chosen providerSupported values: ollama, voyage, openai, cohere, google, vertexai
Ollama runs embedding models locally. No API key is required.
Install:
pip install "mcp-project-context-server[ollama]"Prerequisites: Install Ollama and pull an embedding model:
ollama pull nomic-embed-textEnvironment Variables:
Variable | Default | Description |
| — | Must be set to |
|
| URL of the Ollama server |
|
| Embedding model to use |
Example:
export EMBED_PROVIDER=ollama
export OLLAMA_HOST=http://localhost:11434 # Optional — this is the default
export OLLAMA_EMBED_MODEL=nomic-embed-text # Optional — this is the defaultPopular models:
Model | Size | Notes |
| ~274 MB | Fast, good general purpose |
| ~669 MB | Higher quality |
| ~46 MB | Lightweight, lower quality |
Voyage AI provides embedding models optimized for code and technical content.
Install:
pip install "mcp-project-context-server[voyage]"Getting an API Key:
Sign up at voyageai.com
Navigate to Dashboard → API Keys
Click Create new key, give it a name, and copy the key value
Environment Variables:
Variable | Default | Description |
| — | Must be set to |
| — | Required. Your Voyage AI API key |
|
| Embedding model to use |
Example:
export EMBED_PROVIDER=voyage
export VOYAGE_API_KEY=pa-...
export VOYAGE_EMBED_MODEL=voyage-code-3 # OptionalRecommended models:
Model | Notes |
| Code-optimized, default |
| General purpose |
| Faster, lower cost |
Install:
pip install "mcp-project-context-server[openai]"Getting an API Key:
Sign up or log in at platform.openai.com
Navigate to Dashboard → API Keys
Click Create new secret key, give it a name, and copy the key immediately — it is only shown once
Billing note: OpenAI API access is pay-per-use. Add a payment method at platform.openai.com/account/billing before your free credits run out.
Environment Variables:
Variable | Default | Description |
| — | Must be set to |
| — | Required. Your OpenAI API key |
|
| Embedding model to use |
Example:
export EMBED_PROVIDER=openai
export OPENAI_API_KEY=sk-...
export OPENAI_EMBED_MODEL=text-embedding-3-small # OptionalRecommended models:
Model | Dimensions | Notes |
| 1536 | Fast, cost-effective, default |
| 3072 | Highest quality |
Install:
pip install "mcp-project-context-server[cohere]"Getting an API Key:
Sign up or log in at dashboard.cohere.com
Navigate to API Keys in the left sidebar
Click New Trial Key (free tier, rate-limited) or New Production Key, then copy the value
Environment Variables:
Variable | Default | Description |
| — | Must be set to |
| — | Required. Your Cohere API key |
|
| Embedding model to use |
Example:
export EMBED_PROVIDER=cohere
export COHERE_API_KEY=...
export COHERE_EMBED_MODEL=embed-english-v3.0 # OptionalRecommended models:
Model | Notes |
| English, default |
| 100+ languages |
Uses the Google AI Studio API (Gemini embedding models).
Install:
pip install "mcp-project-context-server[google]"Getting an API Key:
Sign in at aistudio.google.com
Click Get API key in the top navigation
Click Create API key — choose an existing Google Cloud project or create a new one
Copy the generated key
Note: Google AI Studio keys are suitable for development and personal use. For production workloads with higher quotas and enterprise SLAs, use Google Vertex AI instead.
Environment Variables:
Variable | Default | Description |
| — | Must be set to |
| — | Required. Your Google AI Studio API key |
|
| Embedding model to use |
Example:
export EMBED_PROVIDER=google
export GOOGLE_API_KEY=AIza...
export GOOGLE_EMBED_MODEL=text-embedding-004 # OptionalUses the Vertex AI SDK with Google Cloud Application Default Credentials (ADC). No API key is required — authentication is handled through your Google Cloud identity.
Install:
pip install "mcp-project-context-server[google-vertex]"Prerequisites:
Enable the Vertex AI API in your Google Cloud project:
Search for Vertex AI API and click Enable
Authenticate using Application Default Credentials. For local development:
gcloud auth application-default loginFor production environments (e.g. Cloud Run, GKE), assign a service account with the Vertex AI User role (roles/aiplatform.user) to your workload, and set GOOGLE_APPLICATION_CREDENTIALS if using a key file.
Environment Variables:
Variable | Default | Description |
| — | Must be set to |
| — | Required. Your Google Cloud project ID |
| — | Required. Google Cloud region (e.g. |
|
| Embedding model to use |
Example:
export EMBED_PROVIDER=vertexai
export VERTEXAI_PROJECT=my-gcp-project-id
export VERTEXAI_LOCATION=us-central1
export VERTEXAI_EMBED_MODEL=text-embedding-004 # OptionalThe vector store is selected by the VECTOR_STORE_PROVIDER environment variable. Defaults to chroma-local.
Supported values: chroma-local, chroma-http, pgvector
Persists embeddings in a local directory. Included in the core package — no extra installation required.
Environment Variables:
Variable | Default | Description |
|
| Set to |
|
| Directory where ChromaDB stores its data |
Example:
export VECTOR_STORE_PROVIDER=chroma-local # Optional — this is the default
export CHROMA_DIR=~/.mcp-data/chroma # Optional — this is the defaultConnects to a remote or containerized ChromaDB instance over HTTP.
Environment Variables:
Variable | Default | Description |
|
| Must be set to |
|
| ChromaDB server hostname |
|
| ChromaDB server port |
| (none) | API key for ChromaDB Cloud or authenticated instances |
Example:
export VECTOR_STORE_PROVIDER=chroma-http
export CHROMA_HOST=chroma.example.com
export CHROMA_PORT=8000
export CHROMA_API_KEY=your-chroma-api-key # OptionalStores embeddings in a PostgreSQL database using the pgvector extension.
Install:
pip install "mcp-project-context-server[pgvector]"Prerequisites: A PostgreSQL instance (13+) with the pgvector extension enabled:
CREATE EXTENSION IF NOT EXISTS vector;Environment Variables:
Variable | Default | Description |
|
| Must be set to |
| — | Required. PostgreSQL connection string |
Example:
export VECTOR_STORE_PROVIDER=pgvector
export PGVECTOR_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydbThe repository provider controls where the server reads project files from. Defaults to local.
Supported values: local, github, gitlab, gitea
Reads files from the local filesystem. No additional configuration required.
Environment Variables:
Variable | Default | Description |
|
| Set to |
| (from tool call) | Override the project path at server startup |
Reads files from GitHub repositories via the GitHub REST API.
Getting a Personal Access Token:
Click Generate new token (classic) or Fine-grained personal access tokens
Classic: grant the repo scope (or public_repo for public repositories only)
Fine-grained: grant Contents: Read-only on the target repositories
Copy the generated token
Environment Variables:
Variable | Default | Description |
|
| Must be set to |
| (empty) | GitHub personal access token. Required for private repos |
|
| Override for GitHub Enterprise Server |
|
| Default branch when none is specified |
Example:
export REPO_PROVIDER=github
export REPO_AUTH_TOKEN=ghp_...
# GitHub Enterprise only:
export REPO_BASE_URL=https://github.example.com/api/v3Reads files from GitLab repositories via the GitLab REST API.
Getting a Personal Access Token:
Navigate to User Settings → Access Tokens (profile menu → Edit profile → Access Tokens)
Click Add new token
Grant at minimum the read_api scope
Set an expiry date and click Create personal access token
Copy the token immediately — it is not shown again
Environment Variables:
Variable | Default | Description |
|
| Must be set to |
| (empty) | GitLab personal access token |
|
| Override for self-hosted GitLab instances |
|
| Default branch when none is specified |
Example:
export REPO_PROVIDER=gitlab
export REPO_AUTH_TOKEN=glpat-...
# Self-hosted GitLab only:
export REPO_BASE_URL=https://gitlab.example.comReads files from self-hosted Gitea instances. REPO_BASE_URL is required.
Getting an Access Token:
Log in to your Gitea instance
Go to Settings → Applications (your user avatar → Settings → Applications)
Under Manage Access Tokens, enter a name, select the desired permissions, and click Generate Token
Copy the generated token — it is only shown once
Environment Variables:
Variable | Default | Description |
|
| Must be set to |
| — | Required. Your Gitea instance URL (e.g. |
| (empty) | Gitea access token |
|
| Default branch when none is specified |
Example:
export REPO_PROVIDER=gitea
export REPO_BASE_URL=https://gitea.example.com
export REPO_AUTH_TOKEN=...All repository providers support multi-tenant mode, which restricts file access to an allowlist of approved organizations and repositories. Enable it with REPO_MULTI_TENANT=true.
At least one of APPROVED_ORGS or APPROVED_REPOS must be set when multi-tenant mode is active.
Variable | Default | Description |
|
| Set to |
| (none) | Comma-separated list of approved organization names |
| (none) | Comma-separated list of approved |
Example:
export REPO_MULTI_TENANT=true
export APPROVED_ORGS=my-org,partner-org
export APPROVED_REPOS=other-org/specific-repoThe transport is selected by the MCP_TRANSPORT environment variable. Defaults to stdio.
Standard input/output transport. Compatible with Claude Desktop, Claude Code, Cursor, Continue, VS Code Copilot, and most other MCP clients. No additional installation or configuration required.
export MCP_TRANSPORT=stdio # Optional — this is the default
project-context-serverHTTP/SSE transport for remote deployments, team servers, and cloud integrations.
Install:
pip install "mcp-project-context-server[sse]"Start the server:
export MCP_TRANSPORT=sse
export MCP_HOST=0.0.0.0 # Optional — default is 0.0.0.0
export MCP_PORT=8080 # Optional — default is 8080
project-context-serverThe server exposes two endpoints:
GET /sse — SSE connection endpoint for MCP clients
GET /health — unauthenticated health check
Authentication:
| Description |
| No authentication. Use only on trusted private networks. |
| Static token via |
| Google Cloud identity token validation. For use with Agent Engine and service-to-service calls. |
Bearer token example:
export MCP_TRANSPORT=sse
export MCP_AUTH_TYPE=bearer
export MCP_AUTH_TOKEN=your-secret-token
project-context-serverGoogle IAM example:
export MCP_TRANSPORT=sse
export MCP_AUTH_TYPE=google-iam
export GOOGLE_IAM_AUDIENCE=https://my-service.example.com # Recommended
export GOOGLE_APPROVED_SERVICE_ACCOUNTS=sa@project.iam.gserviceaccount.com # Optional allowlist
project-context-serverSSE environment variables:
Variable | Default | Description |
|
| Must be set to |
|
| Bind address |
|
| Listen port |
|
| Authentication: |
| — | Required when |
| (none) | Expected |
| (none) | Path to service account JSON key (uses ADC if unset) |
| (none) | Comma-separated allowed caller service account emails |
The examples below use Ollama as the embedding provider and ChromaDB local as the vector store — the simplest setup with no API key requirements. Substitute environment variables for your chosen providers using the reference in Embedding Providers and Vector Stores.
Detailed client docs with full per-provider configuration matrices are available in
docs/clients/. Those docs are currently being updated to correct some environment variable names from the old implementation — seedocs/client-setup-expansion.mdfor status and the correct variable reference.
Install the server:
pip install "mcp-project-context-server[ollama]"Locate the config file for your OS:
OS | Config File |
Windows |
|
macOS |
|
Linux |
|
Add the server to claude_desktop_config.json:
Windows:
{
"mcpServers": {
"project-context": {
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}macOS / Linux:
{
"mcpServers": {
"project-context": {
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}Restart Claude Desktop and verify the server appears in the MCP tools list.
Install the server:
pip install "mcp-project-context-server[ollama]"Add the MCP server using one of two methods:
Option A — CLI:
claude mcp add project-context \
-e EMBED_PROVIDER=ollama \
-e OLLAMA_HOST=http://localhost:11434 \
-e OLLAMA_EMBED_MODEL=nomic-embed-text \
-- python -m mcp_project_context_serverOption B — Config file:
Scope | Location |
User (global) |
|
Project |
|
{
"mcpServers": {
"project-context": {
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}Verify the server is connected:
claude mcp listInstall the server (see Installation)
Choose a config scope:
Scope | Windows | macOS / Linux |
Global |
|
|
Project |
|
|
Configure mcp.json:
{
"mcpServers": {
"project-context": {
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}Reload Cursor and use @project-context in the chat panel.
Install the Continue extension for VS Code or JetBrains
Locate the config file:
OS | Config File |
Windows |
|
macOS / Linux |
|
Add to config.yaml:
mcpServers:
- name: project-context
command: python
args:
- "-m"
- mcp_project_context_server
env:
EMBED_PROVIDER: "ollama"
OLLAMA_HOST: "http://localhost:11434"
OLLAMA_EMBED_MODEL: "nomic-embed-text"Or if using config.json:
{
"mcpServers": [
{
"name": "project-context",
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
]
}Install the server (see Installation)
Locate the MCP config file:
OS | Config File |
Windows |
|
macOS / Linux |
|
Configure mcp_config.json (create if it does not exist):
{
"mcpServers": {
"project-context": {
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}Restart Windsurf and verify the server appears under Settings → MCP Servers.
MCP support is built into VS Code via GitHub Copilot (no separate extension required). Requires VS Code 1.99+ with the Copilot extension.
Install the server (see Installation)
Choose a config scope:
Option A — Workspace (.vscode/mcp.json):
{
"servers": {
"project-context": {
"type": "stdio",
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}Option B — User settings (settings.json):
{
"mcp": {
"servers": {
"project-context": {
"type": "stdio",
"command": "python",
"args": ["-m", "mcp_project_context_server"],
"env": {
"EMBED_PROVIDER": "ollama",
"OLLAMA_HOST": "http://localhost:11434",
"OLLAMA_EMBED_MODEL": "nomic-embed-text"
}
}
}
}
}Use in Copilot Chat by switching to Agent mode — MCP tools are available automatically.
Tool | Description |
| Indexes all files in |
| Performs semantic search over indexed context |
| Returns the full contents of |
| Writes a session note to |
| Lists available repositories via the configured repository provider |
# Semantic search
search_project_context(
query="How do we handle authentication?",
n_results=5
)
# Load full context
load_project_context()
# Returns: project.md, all ADRs, latest session file
# Save session notes
save_session_summary(
summary="Investigated chunking strategy alternatives, decided on fixed-size for now"
)
# Rebuild the index
index_project_context()Variable | Provider | Default | Required |
| All | — | Yes |
|
|
| No |
|
|
| No |
|
| — | Yes |
|
|
| No |
|
| — | Yes |
|
|
| No |
|
| — | Yes |
|
|
| No |
|
| — | Yes |
|
|
| No |
|
| — | Yes |
|
| — | Yes |
|
|
| No |
Variable | Store | Default | Required |
| All |
| No |
|
|
| No |
|
|
| No |
|
|
| No |
|
| (none) | No |
|
| — | Yes (for pgvector) |
Variable | Provider | Default | Required |
| All |
| No |
|
| (from tool call) | No |
|
| (empty) | No (required for private repos) |
|
| (provider default) | Yes for |
|
|
| No |
| All |
| No |
| All (multi-tenant) | (none) | Yes (if multi-tenant, with no APPROVED_REPOS) |
| All (multi-tenant) | (none) | Yes (if multi-tenant, with no APPROVED_ORGS) |
Variable | Default | Required |
|
| No |
|
| No |
|
| No |
|
| No |
| — | Yes (if |
| (none) | No |
| (none) | No |
| (none) | No |
mcp-project-context-server/
├── src/mcp_project_context_server/
│ ├── server.py # MCP server entry point and tool registry
│ ├── exceptions.py # Shared exception types
│ ├── tools/
│ │ ├── index_context.py # index_project_context tool
│ │ ├── search_context.py # search_project_context tool
│ │ ├── load_context.py # load_project_context tool
│ │ ├── save_session.py # save_session_summary tool
│ │ └── list_repositories.py # list_repositories tool
│ ├── integrations/
│ │ ├── embeddings/
│ │ │ ├── base.py # EmbeddingProvider Protocol
│ │ │ ├── registry.py # Provider factory (EMBED_PROVIDER)
│ │ │ ├── ollama/client.py
│ │ │ ├── voyage/client.py
│ │ │ ├── openai/client.py
│ │ │ ├── cohere/client.py
│ │ │ ├── google/client.py
│ │ │ └── vertexai/client.py
│ │ ├── vectorstore/
│ │ │ ├── base.py # VectorStoreProvider Protocol
│ │ │ ├── registry.py # Provider factory (VECTOR_STORE_PROVIDER)
│ │ │ ├── chroma_local/client.py
│ │ │ ├── chroma_http/client.py
│ │ │ └── pgvector/client.py
│ │ ├── repository/
│ │ │ ├── base.py # RepositoryProvider Protocol
│ │ │ ├── registry.py # Provider factory (REPO_PROVIDER)
│ │ │ ├── local/client.py
│ │ │ ├── github/client.py
│ │ │ ├── gitlab/client.py
│ │ │ └── gitea/client.py
│ │ └── transport/
│ │ ├── stdio.py
│ │ └── sse.py
│ └── helpers/
│ └── context.py # Utility functions
├── .context/ # Project context directory
│ ├── project.md # Project overview
│ ├── sessions/ # Session notes
│ └── decisions/ # Architecture Decision Records
├── tests/
│ ├── unit/ # Unit tests (mocked dependencies)
│ └── integration/ # Integration tests (real services)
├── docs/
│ └── client-setup-expansion.md # Per-provider client setup expansion plan
├── README.md
├── CONTRIBUTING.md
├── pyproject.toml
└── LICENSE# Install test dependencies
pip install "mcp-project-context-server[all]"
pip install pytest pytest-asyncio pytest-mock pytest-cov
# Unit tests (no external services required)
pytest tests/unit/
# Integration tests (requires a running embedding provider and vector store)
pytest tests/integration/
# All tests with coverage report
pytest --cov=src/mcp_project_context_server tests/# Format and lint
black src/
isort src/
flake8 src/
mypy src/
# Check coverage
pytest --cov=src/mcp_project_context_server --cov-report=term-missing tests/unit/Auto-reindex: Watchdog-based file monitoring for automatic reindexing
Codebase Indexing: Repomix integration for source code analysis
Enhanced ADR Tools: First-class MCP tools for ADR lifecycle management
Batch Operations: Bulk ADR updates and session imports
Provider Caching: Singleton caching for embedding and vector store providers
Contributions are welcome! See CONTRIBUTING.md for detailed guidelines including commit message standards, ADR requirements, and the PR process.
This project is licensed under the GNU AFFERO GENERAL PUBLIC LICENSE Version 3 — see the LICENSE file for details.
MCP Team: For the Model Context Protocol
ChromaDB: For the embedded vector store
Ollama: For local embedding model hosting
Built with ❤️ for better LLM project understanding
Deterministically find the most recent .context/sessions/*.md file (sorted by filename, not semantic relevance). Pass the returned path to load_context_files to load it — do not rely on this tool's snippets alone.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes | Absolute filesystem path, a short 'owner/repo' identifier, or a full https:// repository URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behavioral details: the selection is deterministic and based on filename ordering, not semantic relevance. This is crucial for understanding how the tool behaves and prevents misinterpretation. No annotations are present, so the description carries this responsibility well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that convey all essential information without any filler. The structure is efficient, front-loading the core purpose and then providing necessary usage guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description gives sufficient context for the tool's role: it identifies the file type, explains how the latest is determined, and tells the agent the next step (pass to load_context_files). It also warns against a common misuse (relying on snippets), making the tool's place in the overall workflow clear.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter `project_path` is fully documented in the schema with acceptable formats (absolute path, owner/repo, or full URL). The description itself does not add extra semantic detail about the parameter, but with 100% schema coverage it does not need to. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: to deterministically find the most recent .context/sessions/*.md file. It specifies the resource type and the exact operation, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit usage instructions: pass the returned path to `load_context_files` and warns against relying on the tool's snippets alone. This tells the agent exactly how to use the result and what to avoid, which is ideal guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Re-index the .context/ directory into the vector store. Run this after updating project.md, adding ADRs, or refreshing BUNDLE.md.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully disclose behavior. It only says 'Re-index...' without explaining whether the operation is destructive, whether it overwrites existing data, or what the impact is on the vector store. This is a significant gap for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single two-sentence paragraph that is concise and front-loaded. The first sentence states the action, the second gives usage triggers. No unnecessary words, and each sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one param, no output schema, no annotations), the description covers the basic purpose and usage triggers. However, it lacks details about the parameter and the effect on the vector store, making it minimally viable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The only parameter is project_path, and the schema description coverage is 0%. The description does not mention project_path or provide any additional meaning beyond its name. It relies on the parameter name being self-explanatory, but adds no context about format or restrictions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action: 'Re-index the .context/ directory into the vector store.' It also provides context on when to run it, which helps understand its purpose. However, it does not explicitly distinguish from siblings like search_project_context, but the unique action 're-index' sets it apart.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear triggers for use: 'after updating project.md, adding ADRs, or refreshing BUNDLE.md.' This provides good guidance on when to use the tool. It lacks explicit when-not-to-use instructions or alternatives, but the given context is sufficient for most cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List repositories accessible via the configured repository provider. In multi-tenant deployments, use this to discover which repositories are available before calling other tools. Optionally filter by organisation name.
| Name | Required | Description | Default |
|---|---|---|---|
| org | No | Optional: filter results to repositories in this organisation. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only adds 'accessible via configured provider', but does not disclose pagination, rate limits, auth needs, or behavior when provider is unavailable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, compact and front-loaded. No unnecessary words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, and description omits return format, pagination, ordering, or error handling. For a simple list tool, it is borderline adequate but lacks completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and parameter description in schema is clear. Description repeats essentially the same info, adding no new semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (list) and resource (repositories), and distinguishes from sibling tools which focus on project context and sessions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises using this tool for discovery in multi-tenant deployments before other tools, and mentions optional filtering. Lacks when-not-to-use or alternatives, but siblings are unrelated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Load specific .context/-relative files into the active context. Each loaded file is tagged with its path and a SHA-512 hash of its contents so reload_active_context_file can later detect changes. Only pass files you actually need — do not load the whole .context/ tree.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | List of .context/-relative file paths to load, e.g. 'decisions/0007-use-pgvector.md'. | |
| project_path | Yes | Absolute filesystem path, a short 'owner/repo' identifier, or a full https:// repository URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that files are loaded into context and tagged with hashes for change detection, but does not explicitly state whether the operation is read-only or if there are any side effects beyond modifying the active context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two clear sentences, and front-loads the core action followed by useful detail. No extraneous information is included.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description explains the tool's behavior and its relationship to reload_active_context_file, but does not mention what the tool returns or whether there is any output. Since there is no output schema, this gap is minor but present.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described: 'files' explains the relative path format with an example, and 'project_path' lists the three accepted forms (absolute path, owner/repo, or URL). This exceeds the schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool loads specific .context/-relative files into the active context, and explains the tagging mechanism with path and SHA-512 hash. This makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance to only pass files actually needed and to avoid loading the whole tree, but does not directly contrast with sibling tools like search_context_index or reload_active_context_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether files currently held in active context (previously loaded via load_context_files) have changed on disk, by comparing their known SHA-512 hash against the current one. Returns fresh tagged content for changed files, a short 'no change' message for unchanged files, and 'not found' for deleted files.
| Name | Required | Description | Default |
|---|---|---|---|
| files | Yes | List of {path, known_sha512} entries for files currently in active context. | |
| project_path | Yes | Absolute filesystem path, a short 'owner/repo' identifier, or a full https:// repository URL. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility. It transparently discloses the comparison behavior and the three distinct outcomes: fresh content for changed files, 'no change' for unchanged, and 'not found' for deleted. This gives the agent a complete picture of the tool's behavior without hidden side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, using two sentences to convey the core action and expected outcomes. There is no redundant or extraneous information, and the structure is logical, starting with the action and then describing the return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is no output schema, the description explicitly explains what the tool returns for each possible scenario (changed, unchanged, deleted). With only two parameters and a clear return contract, the description is sufficiently complete for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already provides 100% coverage of both parameters, including descriptions for 'files' (list of path and known_sha512) and 'project_path'. The tool description does not add significant extra meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: checking whether files in active context have changed on disk by comparing SHA-512 hashes. It also distinguishes itself from the sibling tool load_context_files, which presumably loads files, by focusing on change detection and returning updated content only for modified files.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need to detect changes to already-loaded files, and it clarifies that unchanged files yield a 'no change' message and deleted files yield 'not found'. It does not explicitly mention alternatives or when not to use it, but the purpose is clear enough for the agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Save a summary of the current session to .context/sessions/YYYY-MM-DD.md. Call this at the end of a session with a concise summary of what was done.
| Name | Required | Description | Default |
|---|---|---|---|
| summary | Yes | Markdown summary: what was worked on, decisions made, next steps. | |
| project_path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It states the output location and naming convention but does not disclose overwrite behavior, directory creation, or any side effects. Basic but adequate for a simple write operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences front-load the key information: purpose, destination, and usage timing. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given simple parameters and no output schema or annotations, the description covers the essential aspects. It could mention whether the file is created/overwritten, but the overall completeness is high for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 50%. The description adds meaning to 'summary' by listing what to include (work done, decisions, next steps). However, 'project_path' remains unexplained beyond its type, missing an opportunity to clarify its format or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool saves a session summary to a specific file path, distinguishing it from sibling tools that index, load, or search project context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to call at end of session with a concise summary, providing clear when-to-use guidance. Does not discuss alternatives or when not to use, but the context with sibling tools implies differentiation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantically search only the architecture decision records under .context/decisions/. Use this to find ADRs relevant to your current task, then pass their paths to load_context_files — do not rely on this tool's snippets alone. If you need to search across all files in the project, use search_project_files instead.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| n_results | No | ||
| project_path | Yes | Absolute filesystem path, a short 'owner/repo' identifier, or a full https:// repository URL. |
| Name | Required | Description |
|---|---|---|
| results | Yes | Individual matching hits, one per matched chunk. |
| warning | No | Present only when the index was built with a different embedding provider/model. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description reveals that the tool returns snippets (not full content) and that a follow-up load_context_files is needed for full ADRs. It also implies a semantic search mechanism. However, it does not explicitly state read-only behavior or output structure, though these are not critical given the search context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences that efficiently convey purpose, usage, and alternatives. It is front-loaded with the core action and includes necessary caveats without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity and the existence of an output schema, the description adequately covers how to invoke it and what to do with results. The note to load full context files is particularly important and included, making the description sufficient for correct usage.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides descriptions for query and project_path, and the tool description reinforces their purpose. However, n_results is only given a default value without any explanation in either schema or description, leaving its meaning partially unclear to the agent.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function: semantically searching architecture decision records within .context/decisions/. It also distinguishes this tool from alternatives like search_project_files and search_context_index, making its scope unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs when to use this tool (find ADRs for the current task) and when to use an alternative (search all project files via search_project_files). It also advises not to rely solely on snippets and to load full context files, providing complete usage guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantically search the whole indexed project context. Use this first to find which files are relevant to your task, then pass their paths to load_context_files — do not rely on this tool's snippets alone.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| n_results | No | ||
| project_path | Yes | Absolute filesystem path, a short 'owner/repo' identifier, or a full https:// repository URL. |
| Name | Required | Description |
|---|---|---|
| results | Yes | Individual matching hits, one per matched chunk. |
| warning | No | Present only when the index was built with a different embedding provider/model. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must convey behavior. It discloses that the tool returns snippets and file paths ('find which files are relevant' and 'do not rely on this tool's snippets alone'), implying a read-only search operation. It does not explicitly state it has no side effects, but the nature of a search tool makes that clear. This is sufficient transparency, though not perfect.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, consisting of two sentences. It directly states the purpose, usage, and a caution without any unnecessary words or repetition. The structure is clean and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description provides essential context for the tool's role in a workflow (search first, then load files) and warns against over-reliance on snippets. It does not detail the output schema, but the information about snippets and relevant files is enough for the agent to understand what to expect. Given the tool's simplicity, this is nearly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema descriptions cover `query` and `project_path`, but `n_results` lacks a description (only a default of 5). The tool description does not elaborate on `n_results`, leaving its meaning to inference from the tool's purpose. Since schema coverage is 67% and the description adds no additional clarity, the parameter semantics are adequate but not enhanced.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose (semantically search the whole indexed project context) and differentiates it from the sibling tool `load_context_files` by instructing to use this first and then pass file paths to the sibling. The verb 'search' and resource 'context index' are specific, making it distinguishable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidance: 'Use this first to find which files are relevant to your task, then pass their paths to `load_context_files`' and 'do not rely on this tool's snippets alone.' This tells the agent exactly when to use this tool versus the alternative, leaving no ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Semantically search only past session summaries under .context/sessions/. Use this to find prior session notes relevant to a topic, then pass their paths to load_context_files — do not rely on this tool's snippets alone.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language search query | |
| n_results | No | ||
| project_path | Yes | Absolute filesystem path, a short 'owner/repo' identifier, or a full https:// repository URL. |
| Name | Required | Description |
|---|---|---|
| results | Yes | Individual matching hits, one per matched chunk. |
| warning | No | Present only when the index was built with a different embedding provider/model. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It reveals that the search is semantic and returns snippets (implied by 'do not rely on this tool's snippets alone'), but it does not disclose details such as whether the query is case-sensitive, whether results are ranked, or any rate limits. It adds some behavioral context but lacks depth that annotations would typically cover.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with zero fluff. It front-loads the core purpose, then immediately gives usage guidance and a caution. Every clause earns its place, making it efficient and easily parseable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (which covers return values) and a moderately simple tool with 3 parameters, the description covers the essential usage, workflow, and caveat. It tells the agent how to integrate results with another tool, which fully addresses the typical decision points for calling this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 67% (query and project_path are described). The description adds minimal insight beyond the schema; it implies query is natural language but says nothing about n_results semantics or how project_path determines the search scope. It does not compensate for the undocumented n_results parameter, so a baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('semantically search') and a precise resource ('past session summaries under .context/sessions/'). It clearly distinguishes this tool from siblings like search_context_index and search_adr_index by scoping to session summaries, leaving no ambiguity about what it searches.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly says when to use it ('to find prior session notes relevant to a topic') and provides a clear follow-up action ('pass their paths to load_context_files'), while also cautioning not to rely on snippets alone. This gives the agent an explicit workflow and redirects to a sibling tool appropriately.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0find_latest_session_fileload_context_filesload_project_contextreload_active_context_filesearch_adr_indexsearch_context_indexsearch_project_contextsearch_session_filesv0.1.0index_project_contextlist_repositoriesload_project_contextsave_session_summarysearch_project_contextScored across 9 tools
Most tools have clearly distinct purposes: search, load, reload, index, save, and list are all separate actions. The only mild ambiguity is among the three semantic search tools, where search_adr_index and search_session_files are subsets of search_context_index, but the descriptions explicitly scope each one.
All tool names follow a consistent lowercase snake_case verb_noun pattern: search_context_index, save_session_summary, load_context_files, reload_active_context_file, etc. The pattern is predictable and makes the action and target clear for every tool.
Nine tools is a well-scoped size for a project-context management server. Each tool covers a meaningful part of the workflow: indexing, searching, loading, reloading, and session handling. No tool feels redundant enough to remove, though list_repositories is slightly tangential.
The core lifecycle is covered: context is indexed, searchable, loadable, reloadable, and session summaries can be saved and found. Minor gaps exist, such as no dedicated tool to list all context files or explicitly unload loaded files, but agents can work around these via search and natural context management.
Cloud-hosted MCP server for durable AI memory
An MCP server that gives your AI access to the source code and docs of all public github repos
Persistent memory for AI agents — log and recall conversation context over MCP.
