archgraph-mcp 1.0.0__py3-none-any.whl

archgraph_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""ArchGraph MCP — codebase knowledge graph server."""
+
+__version__ = "0.1.0"

archgraph_mcp/__main__.py

@@ -0,0 +1,144 @@
+"""CLI entry-point for ArchGraph MCP.
+
+Usage:
+    python -m archgraph_mcp analyze ./my_repo
+    python -m archgraph_mcp serve  ./my_repo
+    python -m archgraph_mcp serve  ./my_repo --transport sse --port 3847
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Literal, cast
+
+from archgraph_mcp.graph.builder import GraphBuilder
+from archgraph_mcp.graph.query_engine import QueryEngine
+from archgraph_mcp.logging_config import setup_logging
+from archgraph_mcp.storage.kuzu_store import KuzuStore
+
+
+def _default_store_path() -> str:
+    return os.environ.get("ARCHGRAPH_STORE") or "archgraph.kuzu"
+
+
+def main(argv: list[str] | None = None) -> None:
+    setup_logging()
+    parser = argparse.ArgumentParser(
+        prog="archgraph-mcp",
+        description="Build and query a knowledge graph of your codebase.",
+    )
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    # ---- analyze ----
+    p_analyze = sub.add_parser("analyze", help="Analyze a repository and print summary")
+    p_analyze.add_argument(
+        "repo", type=Path, nargs="?", default=Path(os.environ.get("REPO_PATH", ".")), help="Path to the repository root"
+    )
+    p_analyze.add_argument(
+        "--store",
+        type=str,
+        default=_default_store_path(),
+        help="Kuzu database path (default: archgraph.kuzu or ARCHGRAPH_STORE)",
+    )
+    p_analyze.add_argument(
+        "--semantic-index",
+        action="store_true",
+        help="Build embedding vector index (requires pip install archgraph-mcp[semantic])",
+    )
+
+    # ---- serve ----
+    p_serve = sub.add_parser("serve", help="Start the MCP server")
+    p_serve.add_argument(
+        "repo", type=Path, nargs="?", default=Path(os.environ.get("REPO_PATH", ".")), help="Path to the repository root"
+    )
+    p_serve.add_argument(
+        "--store",
+        type=str,
+        default=_default_store_path(),
+        help="Kuzu database path (default: archgraph.kuzu or ARCHGRAPH_STORE)",
+    )
+    p_serve.add_argument(
+        "--transport",
+        type=str,
+        default=os.environ.get("MCP_TRANSPORT", "stdio"),
+        choices=["stdio", "sse", "streamable-http"],
+        help="MCP transport: stdio (local), sse, or streamable-http (remote)",
+    )
+    p_serve.add_argument(
+        "--port",
+        type=int,
+        default=int(os.environ.get("PORT", "3847")),
+        help="Port for HTTP transports (default 3847, or PORT env)",
+    )
+    p_serve.add_argument(
+        "--graph-ui",
+        action="store_true",
+        help="Expose GET /graph and /api/graph (HTTP transports only; not stdio)",
+    )
+
+    args = parser.parse_args(argv)
+
+    if args.command == "analyze":
+        _run_analyze(args.repo, args.store, semantic_index=args.semantic_index)
+    elif args.command == "serve":
+        graph_ui_flag = args.graph_ui or os.environ.get("GRAPH_UI", "").strip().lower() in (
+            "1",
+            "true",
+            "yes",
+        )
+        _run_serve(args.repo, args.store, args.transport, args.port, graph_ui=graph_ui_flag)
+
+
+def _run_analyze(repo: Path, store_path: str, *, semantic_index: bool = False) -> None:
+    if semantic_index:
+        os.environ["ARCHGRAPH_BUILD_SEMANTIC_INDEX"] = "1"
+
+    builder = GraphBuilder()
+    builder.build_from_repository(repo.resolve())
+
+    resolved = str(Path(store_path).resolve())
+    store = KuzuStore(resolved)
+    store.save_graph(builder.all_nodes(), builder.all_edges())
+
+    from archgraph_mcp.semantic.build import maybe_build_semantic_index
+
+    maybe_build_semantic_index(resolved, builder.all_nodes())
+
+    engine = QueryEngine(builder.graph, builder._node_index, fts_store=store)
+    summary = engine.architecture_summary()
+    store.close()
+    print(json.dumps(summary.model_dump(), indent=2))
+
+
+def _run_serve(
+    repo: Path,
+    store_path: str,
+    transport: str,
+    port: int,
+    *,
+    graph_ui: bool = False,
+) -> None:
+    # FastMCP binds ``self.settings.port`` from values captured when ``mcp`` is constructed
+    # (import time). Set these *before* importing ``mcp_server`` so ``--port`` is honored.
+    os.environ["PORT"] = str(port)
+    os.environ["FASTMCP_PORT"] = str(port)
+
+    from archgraph_mcp.server.mcp_server import initialize, mcp
+
+    log = logging.getLogger("archgraph_mcp")
+    graph_ui_effective = graph_ui and transport != "stdio"
+    if graph_ui and transport == "stdio":
+        log.warning(
+            "--graph-ui is ignored for stdio transport (no HTTP server). "
+            "Use --transport sse or streamable-http to enable /graph.",
+        )
+
+    # Build or load the graph
+    initialize(str(repo), store_path, graph_ui=graph_ui_effective)
+
+    # Let FastMCP handle server startup
+    mcp.run(transport=cast(Literal["stdio", "sse", "streamable-http"], transport))

archgraph_mcp/enums.py

@@ -0,0 +1,27 @@
+"""Deterministic enums for graph node and edge types."""
+
+from enum import StrEnum
+
+
+class NodeType(StrEnum):
+    """Types of nodes in the code knowledge graph."""
+
+    REPOSITORY = "repository"
+    MODULE = "module"
+    FILE = "file"
+    CLASS = "class"
+    FUNCTION = "function"
+    API = "api"
+    DATABASE = "database"
+
+
+class EdgeType(StrEnum):
+    """Types of edges (relationships) in the code knowledge graph."""
+
+    IMPORTS = "imports"
+    CALLS = "calls"
+    DEFINES = "defines"
+    READS_TABLE = "reads_table"
+    WRITES_TABLE = "writes_table"
+    EXPOSES_API = "exposes_api"
+    DEPENDS_ON = "depends_on"

archgraph_mcp/graph/builder.py

@@ -0,0 +1,142 @@
+"""Graph builder — converts parser output into a NetworkX directed graph."""
+
+from __future__ import annotations
+
+import logging
+import time
+from pathlib import Path
+
+import networkx as nx
+
+from archgraph_mcp.enums import EdgeType, NodeType
+from archgraph_mcp.models import Edge, Node
+from archgraph_mcp.parser.base import BaseParser, ParseResult
+from archgraph_mcp.parser.java import JavaParser
+from archgraph_mcp.parser.kotlin import KotlinParser
+from archgraph_mcp.parser.typescript import TypeScriptParser
+from archgraph_mcp.utils.scanner import (
+    detect_language,
+    scan_repository,
+)
+
+logger = logging.getLogger("archgraph_mcp.graph.builder")
+
+# Registry: language string → parser instance
+_PARSERS: dict[str, BaseParser] = {
+    "typescript": TypeScriptParser(),
+    "java": JavaParser(),
+    "kotlin": KotlinParser(),
+}
+
+
+class GraphBuilder:
+    """Incrementally builds a NetworkX DiGraph from a repository."""
+
+    def __init__(self) -> None:
+        self.graph: nx.DiGraph = nx.DiGraph()
+        self._node_index: dict[str, Node] = {}
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def build_from_repository(self, repo_path: Path) -> nx.DiGraph:
+        """Scan, parse, and build the graph for an entire repository."""
+        start = time.perf_counter()
+
+        # Repository root node
+        repo_id = f"repository:{repo_path.name}"
+        self._add_node(
+            Node(
+                id=repo_id,
+                type=NodeType.REPOSITORY,
+                name=repo_path.name,
+            )
+        )
+
+        for source_file in scan_repository(repo_path):
+            self._process_file(source_file, repo_id)
+
+        elapsed = time.perf_counter() - start
+        logger.info(
+            "Graph built: %d nodes, %d edges in %.2fs",
+            self.graph.number_of_nodes(),
+            self.graph.number_of_edges(),
+            elapsed,
+        )
+        return self.graph
+
+    def add_parse_result(self, result: ParseResult) -> None:
+        """Merge a ``ParseResult`` into the graph (for incremental use)."""
+        for node in result.nodes:
+            self._add_node(node)
+        for edge in result.edges:
+            self._add_edge(edge)
+
+    # ------------------------------------------------------------------
+    # Accessors
+    # ------------------------------------------------------------------
+
+    def get_node(self, node_id: str) -> Node | None:
+        """Return the parsed ``Node`` for *node_id*, or ``None`` if unknown."""
+        return self._node_index.get(node_id)
+
+    def all_nodes(self) -> list[Node]:
+        """Return every node currently in the index (order not guaranteed)."""
+        return list(self._node_index.values())
+
+    def all_edges(self) -> list[Edge]:
+        """Return all edges in the graph, with types taken from edge attributes."""
+        edges: list[Edge] = []
+        for u, v, data in self.graph.edges(data=True):
+            edges.append(Edge(source=u, target=v, type=data.get("type", EdgeType.DEPENDS_ON)))
+        return edges
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _process_file(self, path: Path, repo_id: str) -> None:
+        """Parse *path* if supported and wire its file node to *repo_id*."""
+        language = detect_language(path)
+        if language is None:
+            return
+
+        parser = _PARSERS.get(language)
+        if parser is None:
+            logger.debug("No parser for language %s, skipping %s", language, path)
+            return
+
+        try:
+            source = path.read_bytes()
+        except (OSError, PermissionError):
+            logger.warning("Cannot read file: %s", path)
+            return
+
+        result = parser.parse_file(path, source)
+        self.add_parse_result(result)
+
+        # Link file node to repository
+        for node in result.nodes:
+            if node.type == NodeType.FILE:
+                self._add_edge(
+                    Edge(
+                        source=repo_id,
+                        target=node.id,
+                        type=EdgeType.DEPENDS_ON,
+                    )
+                )
+
+    def _add_node(self, node: Node) -> None:
+        """Insert *node* into the index and NetworkX graph (first write wins)."""
+        if node.id not in self._node_index:
+            self._node_index[node.id] = node
+            self.graph.add_node(node.id, **node.model_dump())
+
+    def _add_edge(self, edge: Edge) -> None:
+        """Add *edge*; create stub endpoints if missing so NetworkX stays consistent."""
+        # Ensure both endpoints exist as graph nodes (at minimum as stubs)
+        for nid in (edge.source, edge.target):
+            if nid not in self.graph:
+                self.graph.add_node(nid)
+        self.graph.add_edge(edge.source, edge.target, type=edge.type)

archgraph_mcp/graph/query_engine.py

@@ -0,0 +1,211 @@
+"""Query engine — graph traversal algorithms on the code knowledge graph."""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections import deque
+from typing import Protocol
+
+import networkx as nx
+
+from archgraph_mcp.enums import EdgeType, NodeType
+from archgraph_mcp.models import (
+    ArchitectureSummary,
+    Edge,
+    GraphQuery,
+    ImpactResult,
+    Node,
+)
+
+logger = logging.getLogger("archgraph_mcp.graph.query_engine")
+
+
+class _SupportsFtsSearch(Protocol):
+    def search_nodes_fts(
+        self,
+        query: str,
+        node_type: NodeType | None,
+        limit: int,
+        node_by_id: dict[str, Node],
+    ) -> list[Node]: ...
+
+
+class QueryEngine:
+    """Executes queries against a built NetworkX graph."""
+
+    def __init__(
+        self,
+        graph: nx.DiGraph,
+        node_index: dict[str, Node] | None = None,
+        *,
+        fts_store: _SupportsFtsSearch | None = None,
+    ) -> None:
+        self._g = graph
+        self._nodes = node_index or {}
+        self._fts_store = fts_store
+
+    @property
+    def node_index(self) -> dict[str, Node]:
+        """Map of node id → :class:`Node` (for tools that need lookup after search)."""
+        return self._nodes
+
+    # ------------------------------------------------------------------
+    # MCP tool: search_nodes
+    # ------------------------------------------------------------------
+
+    def search_nodes(
+        self,
+        query: str,
+        node_type: NodeType | None = None,
+        limit: int = 50,
+    ) -> list[Node]:
+        """FTS-ranked search when a store is configured; else substring on name/id."""
+        start = time.perf_counter()
+        if self._fts_store is not None:
+            fts_matches = self._fts_store.search_nodes_fts(query, node_type, limit, self._nodes)
+            if fts_matches:
+                elapsed = time.perf_counter() - start
+                logger.info("search_nodes(%r) fts → %d results in %.3fs", query, len(fts_matches), elapsed)
+                return fts_matches
+
+        query_lower = query.lower()
+        matches: list[Node] = []
+        for node in self._nodes.values():
+            if node_type and node.type != node_type:
+                continue
+            if query_lower in node.name.lower() or query_lower in node.id.lower():
+                matches.append(node)
+                if len(matches) >= limit:
+                    break
+        logger.info("search_nodes(%r) → %d results in %.3fs", query, len(matches), time.perf_counter() - start)
+        return matches
+
+    # ------------------------------------------------------------------
+    # MCP tool: trace_dependencies (downstream)
+    # ------------------------------------------------------------------
+
+    def trace_dependencies(self, gq: GraphQuery) -> list[Node]:
+        """BFS downstream — what does *node_id* depend on?"""
+        return self._bfs(gq.node_id, gq.max_depth, successors=True)
+
+    # ------------------------------------------------------------------
+    # MCP tool: trace_dependents (upstream)
+    # ------------------------------------------------------------------
+
+    def trace_dependents(self, gq: GraphQuery) -> list[Node]:
+        """BFS upstream — what depends on *node_id*?"""
+        return self._bfs(gq.node_id, gq.max_depth, successors=False)
+
+    # ------------------------------------------------------------------
+    # MCP tool: impact_analysis
+    # ------------------------------------------------------------------
+
+    def impact_analysis(self, gq: GraphQuery) -> ImpactResult:
+        """BFS upstream to determine everything affected by a change to *node_id*."""
+        start = time.perf_counter()
+        affected = self._bfs(gq.node_id, gq.max_depth, successors=False)
+        affected_edges: list[Edge] = []
+
+        affected_ids = {n.id for n in affected} | {gq.node_id}
+        for u, v, data in self._g.edges(data=True):
+            if u in affected_ids and v in affected_ids:
+                affected_edges.append(
+                    Edge(
+                        source=u,
+                        target=v,
+                        type=data.get("type", EdgeType.DEPENDS_ON),
+                    )
+                )
+
+        logger.info("impact_analysis(%s) → %d nodes in %.3fs", gq.node_id, len(affected), time.perf_counter() - start)
+        return ImpactResult(
+            source_node=gq.node_id,
+            affected_nodes=affected,
+            affected_edges=affected_edges,
+            depth=gq.max_depth,
+        )
+
+    # ------------------------------------------------------------------
+    # MCP tool: trace_path
+    # ------------------------------------------------------------------
+
+    def trace_path(self, source_id: str, target_id: str) -> list[Node]:
+        """Shortest path between *source_id* and *target_id* (undirected graph).
+
+        Only nodes present in the internal index are included; intermediate
+        graph ids without metadata are skipped.
+        """
+        try:
+            path_ids = nx.shortest_path(self._g.to_undirected(), source_id, target_id)
+        except (nx.NetworkXNoPath, nx.NodeNotFound):
+            return []
+        return [self._nodes[nid] for nid in path_ids if nid in self._nodes]
+
+    # ------------------------------------------------------------------
+    # MCP tool: architecture_summary
+    # ------------------------------------------------------------------
+
+    def architecture_summary(self) -> ArchitectureSummary:
+        """Return a compact high-level summary of the graph."""
+        node_counts: dict[str, int] = {}
+        languages: set[str] = set()
+        files_analyzed = 0
+
+        for node in self._nodes.values():
+            key = node.type.value
+            node_counts[key] = node_counts.get(key, 0) + 1
+            if node.type == NodeType.FILE:
+                files_analyzed += 1
+            if node.language:
+                languages.add(node.language)
+
+        edge_counts: dict[str, int] = {}
+        for _, _, data in self._g.edges(data=True):
+            etype = data.get("type", EdgeType.DEPENDS_ON)
+            key = etype.value if isinstance(etype, EdgeType) else str(etype)
+            edge_counts[key] = edge_counts.get(key, 0) + 1
+
+        return ArchitectureSummary(
+            total_nodes=self._g.number_of_nodes(),
+            total_edges=self._g.number_of_edges(),
+            node_counts=node_counts,
+            edge_counts=edge_counts,
+            files_analyzed=files_analyzed,
+            languages=sorted(languages),
+        )
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _bfs(
+        self,
+        start: str,
+        max_depth: int,
+        *,
+        successors: bool,
+    ) -> list[Node]:
+        """Generic BFS. *successors=True* traverses downstream, else upstream."""
+        if start not in self._g:
+            return []
+
+        visited: set[str] = set()
+        queue: deque[tuple[str, int]] = deque([(start, 0)])
+        result: list[Node] = []
+
+        while queue:
+            current, depth = queue.popleft()
+            if current in visited or depth > max_depth:
+                continue
+            visited.add(current)
+
+            if current != start and current in self._nodes:
+                result.append(self._nodes[current])
+
+            neighbors = self._g.successors(current) if successors else self._g.predecessors(current)
+            for neighbor in neighbors:
+                if neighbor not in visited:
+                    queue.append((neighbor, depth + 1))
+
+        return result

archgraph_mcp/logging_config.py

@@ -0,0 +1,27 @@
+"""Structured logging configuration for ArchGraph MCP."""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+
+def setup_logging(level: int = logging.INFO) -> logging.Logger:
+    """Configure and return the root logger for archgraph_mcp."""
+    logger = logging.getLogger("archgraph_mcp")
+    if logger.handlers:
+        return logger
+
+    logger.setLevel(level)
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setLevel(level)
+
+    formatter = logging.Formatter(
+        fmt="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
+        datefmt="%Y-%m-%d %H:%M:%S",
+    )
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+
+    return logger

archgraph_mcp/models.py

@@ -0,0 +1,56 @@
+"""Pydantic data models for structured serialization."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+from archgraph_mcp.enums import EdgeType, NodeType
+
+
+class Node(BaseModel):
+    """A single node in the code knowledge graph."""
+
+    id: str = Field(..., description="Unique identifier, e.g. 'function:auth.loginUser'")
+    type: NodeType
+    name: str
+    file: str | None = None
+    language: str | None = None
+    metadata: dict[str, Any] = Field(default_factory=dict)
+
+
+class Edge(BaseModel):
+    """A directed relationship between two nodes."""
+
+    source: str = Field(..., description="Source node id")
+    target: str = Field(..., description="Target node id")
+    type: EdgeType
+
+
+class GraphQuery(BaseModel):
+    """Parameters for a graph query."""
+
+    node_id: str
+    max_depth: int = Field(default=10, ge=1, le=100)
+    edge_types: list[EdgeType] | None = None
+
+
+class ImpactResult(BaseModel):
+    """Result of an impact analysis query."""
+
+    source_node: str
+    affected_nodes: list[Node] = Field(default_factory=list)
+    affected_edges: list[Edge] = Field(default_factory=list)
+    depth: int = 0
+
+
+class ArchitectureSummary(BaseModel):
+    """High-level architecture summary of the graph."""
+
+    total_nodes: int = 0
+    total_edges: int = 0
+    node_counts: dict[str, int] = Field(default_factory=dict)
+    edge_counts: dict[str, int] = Field(default_factory=dict)
+    files_analyzed: int = 0
+    languages: list[str] = Field(default_factory=list)

archgraph_mcp/parser/base.py

@@ -0,0 +1,61 @@
+"""Abstract base parser interface."""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+from tree_sitter import Node as TSNode
+
+from archgraph_mcp.models import Edge, Node
+
+logger = logging.getLogger("archgraph_mcp.parser")
+
+
+def utf8_node_text(node: TSNode) -> str:
+    """Return UTF-8 text for a tree-sitter node, or empty string if absent."""
+    raw = node.text
+    if raw is None:
+        return ""
+    return raw.decode("utf-8")
+
+
+class ParseResult:
+    """Container for nodes and edges extracted from a single file."""
+
+    __slots__ = ("nodes", "edges")
+
+    def __init__(self) -> None:
+        """Create empty node and edge lists."""
+        self.nodes: list[Node] = []
+        self.edges: list[Edge] = []
+
+    def add_node(self, node: Node) -> None:
+        """Append *node* to the result list."""
+        self.nodes.append(node)
+
+    def add_edge(self, edge: Edge) -> None:
+        """Append *edge* to the result list."""
+        self.edges.append(edge)
+
+
+class BaseParser(ABC):
+    """Interface every language parser must implement."""
+
+    language: str  # e.g. "typescript"
+
+    @abstractmethod
+    def parse_file(self, path: Path, source: bytes) -> ParseResult:
+        """Parse *source* and return extracted nodes and edges.
+
+        Implementations must catch internal errors and return a
+        partial ``ParseResult`` rather than raising.
+        """
+
+    # ------- helpers available to subclasses ------
+
+    @staticmethod
+    def _make_id(kind: str, *parts: str) -> str:
+        """Build a deterministic node id, e.g. ``function:auth.login``."""
+        return f"{kind}:{'.'.join(parts)}"