mcp-project-context-server 0.0.7__py3-none-any.whl

mcp_project_context_server/__init__.py

@@ -0,0 +1,6 @@
+"""mcp-project-context-server — MCP server for persistent project context."""
+
+try:
+    from mcp_project_context_server._version import __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"

mcp_project_context_server/__main__.py

@@ -0,0 +1,3 @@
+from mcp_project_context_server.server import run
+
+run()

mcp_project_context_server/helpers/context.py

@@ -0,0 +1,32 @@
+"""Shared helpers for .context/ directory resolution and file reading."""
+
+from pathlib import Path
+
+
+def find_context_dir(project_path: str | Path) -> Path | None:
+    """Walk up from project_path to find a .context/ directory."""
+    p = Path(project_path).resolve()
+    for candidate in [p, *p.parents]:
+        ctx = candidate / ".context"
+        if ctx.is_dir():
+            return ctx
+    return None
+
+
+def collection_name_for(context_dir: Path) -> str:
+    """Derive a stable ChromaDB collection name from the project root.
+
+    Always based on context_dir.parent so it is consistent regardless of
+    whether the caller passed a project root, a subdirectory, or a file path.
+    """
+    project_name = context_dir.parent.name
+    return f"ctx_{project_name}".replace("-", "_").replace(" ", "_")[:63]
+
+
+def read_context_files(context_dir: Path) -> dict[str, str]:
+    """Read all markdown files from .context/ into a dict.
+
+    Keys use POSIX-style forward slashes (Path.as_posix()) so that ChromaDB
+    document IDs and metadata are identical on Windows and Linux.
+    """
+    return {md_file.relative_to(context_dir).as_posix(): md_file.read_text(encoding="utf-8") for md_file in context_dir.rglob("*.md")}

mcp_project_context_server/indexing/chroma/indexer.py

@@ -0,0 +1,72 @@
+"""Indexes .context/ files into ChromaDB for semantic search."""
+
+import asyncio
+import os
+import sys
+from pathlib import Path
+
+from mcp_project_context_server.helpers.context import (
+    collection_name_for,
+    find_context_dir,
+    read_context_files,
+)
+from mcp_project_context_server.indexing.ollama.embedder import embed_chunk_async
+from mcp_project_context_server.integrations.chroma.client import chroma_client
+from mcp_project_context_server.integrations.ollama.client import get_async_client
+
+_EMBED_CONCURRENCY: int = int(os.getenv("EMBED_CONCURRENCY", "4"))
+
+
+async def index_project_context(project_path: str | Path) -> str:
+    """Chunk, embed concurrently, and batch-store all .context/ markdown files."""
+    context_dir = find_context_dir(project_path)
+    if not context_dir:
+        return f"No .context/ directory found at or above {project_path}"
+
+    col_name = collection_name_for(context_dir)
+
+    # Drop and recreate for a clean re-index
+    try:
+        chroma_client.delete_collection(col_name)
+    except Exception:
+        pass
+    collection = chroma_client.create_collection(col_name)
+
+    files = read_context_files(context_dir)
+
+    # Build flat list of (doc_id, chunk_text, filename, chunk_index)
+    all_chunks: list[tuple[str, str, str, int]] = []
+    for filename, file_content in files.items():
+        for i, chunk in enumerate(file_content[j : j + 1000] for j in range(0, len(file_content), 1000)):
+            if chunk.strip():
+                all_chunks.append((f"{filename}::{i}", chunk, filename, i))
+
+    if not all_chunks:
+        return f"Indexed 0 chunks from {len(files)} files into collection '{col_name}'"
+
+    # Embed all chunks concurrently, bounded by semaphore
+    async_client = get_async_client()
+    semaphore = asyncio.Semaphore(_EMBED_CONCURRENCY)
+
+    async def _embed(doc_id: str, chunk: str, filename: str, chunk_idx: int):
+        async with semaphore:
+            try:
+                embedding = await embed_chunk_async(chunk, async_client)
+                return (doc_id, chunk, embedding, filename, chunk_idx)
+            except Exception as e:
+                print(f"Warning: failed to embed {doc_id}: {e}", file=sys.stderr)
+                return None
+
+    results = await asyncio.gather(*[_embed(*c) for c in all_chunks])
+
+    # Filter failures, then batch-add everything to ChromaDB in one call
+    valid = [r for r in results if r is not None]
+    if valid:
+        collection.add(
+            ids=[r[0] for r in valid],
+            embeddings=[r[2] for r in valid],
+            documents=[r[1] for r in valid],
+            metadatas=[{"file": r[3], "chunk": r[4]} for r in valid],
+        )
+
+    return f"Indexed {len(valid)} chunks from {len(files)} files into collection '{col_name}'"

mcp_project_context_server/indexing/ollama/embedder.py

@@ -0,0 +1,18 @@
+"""Embedding generation for the indexing pipeline (sync + async)."""
+
+import ollama
+
+from mcp_project_context_server.integrations.ollama.client import (
+    get_embedding,
+    get_embedding_async,
+)
+
+
+def embed_chunk(text: str) -> list[float]:
+    """Generate an embedding vector for a single text chunk."""
+    return get_embedding(text)
+
+
+async def embed_chunk_async(text: str, client: ollama.AsyncClient) -> list[float]:
+    """Async: Generate an embedding vector for a single text chunk."""
+    return await get_embedding_async(text, client)

mcp_project_context_server/integrations/chroma/client.py

@@ -0,0 +1,18 @@
+"""ChromaDB client configuration and singleton."""
+
+import os
+from pathlib import Path
+
+import chromadb
+from chromadb.config import Settings
+
+_chroma_default: Path = Path.home() / ".mcp-data" / "chroma"
+CHROMA_DIR: Path = Path(os.getenv("CHROMA_DIR", str(_chroma_default)))
+CHROMA_DIR.mkdir(parents=True, exist_ok=True)
+
+# chromadb.PersistentClient requires a str — this is the only place a Path is
+# explicitly converted to str, at the external API boundary.
+chroma_client: chromadb.ClientAPI = chromadb.PersistentClient(
+    path=str(CHROMA_DIR),
+    settings=Settings(anonymized_telemetry=False),
+)

mcp_project_context_server/integrations/ollama/client.py

@@ -0,0 +1,28 @@
+"""Ollama client configuration and raw embedding API calls (sync + async)."""
+
+import os
+
+import ollama
+
+OLLAMA_BASE_URL: str = os.getenv("OLLAMA_HOST", "http://localhost:11434")
+EMBED_MODEL: str = os.getenv("EMBED_MODEL", "nomic-embed-text")
+
+
+def get_client() -> ollama.Client:
+    return ollama.Client(host=OLLAMA_BASE_URL)
+
+
+def get_async_client() -> ollama.AsyncClient:
+    return ollama.AsyncClient(host=OLLAMA_BASE_URL)
+
+
+def get_embedding(text: str) -> list[float]:
+    """Call the Ollama embed endpoint and return the embedding vector."""
+    response = get_client().embed(model=EMBED_MODEL, input=text)
+    return list(response.embeddings[0])
+
+
+async def get_embedding_async(text: str, client: ollama.AsyncClient) -> list[float]:
+    """Async: Call the Ollama embed endpoint and return the embedding vector."""
+    response = await client.embed(model=EMBED_MODEL, input=text)
+    return list(response.embeddings[0])

mcp_project_context_server/server.py

@@ -0,0 +1,119 @@
+"""MCP server setup, tool registry, and entry point."""
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+from mcp import types
+from mcp.server import Server
+from mcp.server.stdio import stdio_server
+
+from mcp_project_context_server.tools import (
+    index_context,
+    load_context,
+    save_session,
+    search_context,
+)
+
+_LOG_PATH = Path(r"C:\Users\drahk\.mcp-data\logs\project-context-server.log")
+_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+logging.basicConfig(
+    filename=_LOG_PATH,
+    filemode="a",
+    level=logging.DEBUG,
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+)
+logger = logging.getLogger(__name__)
+
+
+server = Server("project-context")
+
+_TOOL_DEFINITIONS: list[types.Tool] = [
+    types.Tool(
+        name="load_project_context",
+        description=("Load the full project context for the given project path. " "Returns project.md, all ADRs, and the latest session summary. " "You MUST call this at the start of every session."),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "project_path": {
+                    "type": "string",
+                    "description": "Absolute path to the project root or any file within it.",
+                }
+            },
+            "required": ["project_path"],
+        },
+    ),
+    types.Tool(
+        name="search_project_context",
+        description=("Semantically search the indexed project context. " "Use this to find relevant past decisions, architecture notes, " "or code summaries related to your current task."),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "project_path": {"type": "string"},
+                "query": {"type": "string", "description": "Natural language search query"},
+                "n_results": {"type": "integer", "default": 5},
+            },
+            "required": ["project_path", "query"],
+        },
+    ),
+    types.Tool(
+        name="save_session_summary",
+        description=("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."),
+        inputSchema={
+            "type": "object",
+            "properties": {
+                "project_path": {"type": "string"},
+                "summary": {
+                    "type": "string",
+                    "description": "Markdown summary: what was worked on, decisions made, next steps.",
+                },
+            },
+            "required": ["project_path", "summary"],
+        },
+    ),
+    types.Tool(
+        name="index_project_context",
+        description=("Re-index the .context/ directory into the vector store. " "Run this after updating project.md, adding ADRs, or refreshing BUNDLE.md."),
+        inputSchema={
+            "type": "object",
+            "properties": {"project_path": {"type": "string"}},
+            "required": ["project_path"],
+        },
+    ),
+]
+
+_TOOL_HANDLERS = {
+    "load_project_context": load_context.handle,
+    "search_project_context": search_context.handle,
+    "save_session_summary": save_session.handle,
+    "index_project_context": index_context.handle,
+}
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return _TOOL_DEFINITIONS
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> list[types.TextContent]:
+    handler = _TOOL_HANDLERS.get(name)
+    if not handler:
+        return [types.TextContent(type="text", text=f"Unknown tool: {name}")]
+    return await handler(arguments)
+
+
+async def _main() -> None:
+    async with stdio_server() as (read_stream, write_stream):
+        await server.run(read_stream, write_stream, server.create_initialization_options())
+
+
+def run() -> None:
+    logger.info("project-context-server starting")
+    try:
+        asyncio.run(_main())
+    except Exception:
+        logger.exception("Server crashed at top level")
+        raise

mcp_project_context_server/tools/index_context.py

@@ -0,0 +1,13 @@
+"""Tool: index_project_context — re-indexes .context/ into ChromaDB."""
+
+import os
+
+from mcp import types
+
+from mcp_project_context_server.indexing.chroma.indexer import index_project_context
+
+
+async def handle(arguments: dict) -> list[types.TextContent]:
+    _project_path = os.getenv("PROJECT_PATH", arguments["project_path"])
+    result = await index_project_context(_project_path)
+    return [types.TextContent(type="text", text=result)]

mcp_project_context_server/tools/load_context.py

@@ -0,0 +1,43 @@
+"""Tool: load_project_context — loads project.md, ADRs, and last session."""
+
+import os
+
+from mcp import types
+
+from mcp_project_context_server.helpers.context import find_context_dir
+
+
+async def handle(arguments: dict) -> list[types.TextContent]:
+    _project_path = os.getenv("PROJECT_PATH", arguments["project_path"])
+    context_dir = find_context_dir(_project_path)
+    if not context_dir:
+        return [
+            types.TextContent(
+                type="text",
+                text=f"No .context/ directory found near {arguments['project_path']}",
+            )
+        ]
+
+    parts: list[str] = []
+
+    project_md = context_dir / "project.md"
+    if project_md.exists():
+        parts.append(f"## project.md\n\n{project_md.read_text(encoding='utf-8')}")
+
+    decisions_dir = context_dir / "decisions"
+    if decisions_dir.exists():
+        adrs = sorted(decisions_dir.glob("*.md"))
+        if adrs:
+            parts.append("## Architecture Decisions\n")
+            for adr in adrs:
+                parts.append(f"### {adr.name}\n{adr.read_text(encoding='utf-8')}")
+
+    sessions_dir = context_dir / "sessions"
+    if sessions_dir.exists():
+        session_files = sorted(sessions_dir.glob("*.md"))
+        if session_files:
+            latest = session_files[-1]
+            parts.append(f"## Last Session ({latest.stem})\n\n{latest.read_text(encoding='utf-8')}")
+
+    result = "\n\n---\n\n".join(parts)
+    return [types.TextContent(type="text", text=result or "No context files found.")]

mcp_project_context_server/tools/save_session.py

@@ -0,0 +1,43 @@
+"""Tool: save_session_summary — writes a session summary to .context/sessions/."""
+
+import os
+from datetime import datetime
+
+from mcp import types
+
+from mcp_project_context_server.helpers.context import find_context_dir
+
+
+async def handle(arguments: dict) -> list[types.TextContent]:
+    summary: str = arguments["summary"]
+
+    _project_path = os.getenv("PROJECT_PATH", arguments["project_path"])
+    context_dir = find_context_dir(_project_path)
+    if not context_dir:
+        return [
+            types.TextContent(
+                type="text",
+                text=f"No .context/ directory found near {arguments['project_path']}",
+            )
+        ]
+
+    sessions_dir = context_dir / "sessions"
+    sessions_dir.mkdir(exist_ok=True)
+
+    today = datetime.now().strftime("%Y-%m-%d")
+    session_file = sessions_dir / f"{today}.md"
+
+    if session_file.exists():
+        timestamp = datetime.now().strftime("%H:%M")
+        file_content = f"{session_file.read_text(encoding='utf-8')}" f"\n\n### Session at {timestamp}\n\n{summary}"
+    else:
+        file_content = f"# Session: {today}\n\n{summary}"
+
+    session_file.write_text(file_content, encoding="utf-8")
+    # as_posix() gives a consistent forward-slash path regardless of platform.
+    return [
+        types.TextContent(
+            type="text",
+            text=f"Session summary saved to {session_file.as_posix()}",
+        )
+    ]

mcp_project_context_server/tools/search_context.py

@@ -0,0 +1,52 @@
+"""Tool: search_project_context — semantic search over indexed context."""
+
+import os
+from collections.abc import Sequence
+from typing import cast
+
+from mcp import types
+
+from mcp_project_context_server.helpers.context import collection_name_for, find_context_dir
+from mcp_project_context_server.integrations.chroma.client import chroma_client
+from mcp_project_context_server.integrations.ollama.client import get_embedding
+
+
+async def handle(arguments: dict) -> list[types.TextContent]:
+    query: str = arguments["query"]
+    n_results: int = arguments.get("n_results", 5)
+
+    _project_path = os.getenv("PROJECT_PATH", arguments["project_path"])
+    context_dir = find_context_dir(_project_path)
+    if not context_dir:
+        return [
+            types.TextContent(
+                type="text",
+                text=f"No .context/ directory found near {arguments['project_path']}",
+            )
+        ]
+
+    col_name = collection_name_for(context_dir)
+
+    try:
+        collection = chroma_client.get_collection(col_name)
+    except Exception:
+        return [
+            types.TextContent(
+                type="text",
+                text=f"Collection '{col_name}' not found. Run index_project_context first.",
+            )
+        ]
+
+    query_embedding = get_embedding(query)
+    results = collection.query(
+        query_embeddings=cast(list[Sequence[float]], [query_embedding]),
+        n_results=min(n_results, collection.count()),
+    )
+
+    docs = results["documents"]
+    metas = results["metadatas"]
+    if docs is None or metas is None or not docs[0]:
+        return [types.TextContent(type="text", text="No results found.")]
+
+    output_parts = [f"**[{meta['file']}]**\n{doc}" for doc, meta in zip(docs[0], metas[0])]
+    return [types.TextContent(type="text", text="\n\n---\n\n".join(output_parts))]