archgraph-mcp 1.0.0__tar.gz

archgraph_mcp-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 ArchGraph MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

archgraph_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.4
+Name: archgraph-mcp
+Version: 1.0.0
+Summary: MCP server that builds a knowledge graph of a software codebase
+Requires-Python: >=3.12
+License-File: LICENSE
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: networkx>=3.6.1
+Requires-Dist: mcp<2.0,>=1.28.1
+Requires-Dist: uvicorn>=0.51.0
+Requires-Dist: starlette>=1.3.1
+Requires-Dist: tree-sitter>=0.26.0
+Requires-Dist: tree-sitter-typescript>=0.23.2
+Requires-Dist: tree-sitter-java>=0.23.5
+Requires-Dist: tree-sitter-kotlin>=1.1.0
+Requires-Dist: kuzu>=0.11.3
+Provides-Extra: semantic
+Requires-Dist: numpy>=2.5.1; extra == "semantic"
+Provides-Extra: dev
+Requires-Dist: pytest>=9.1.1; extra == "dev"
+Requires-Dist: pytest-asyncio>=1.4.0; extra == "dev"
+Requires-Dist: ruff>=0.15.22; extra == "dev"
+Requires-Dist: mypy>=2.3.0; extra == "dev"
+Requires-Dist: types-networkx>=3.6.1.20260624; extra == "dev"
+Requires-Dist: mdformat>=1.0; extra == "dev"
+Requires-Dist: mdformat-gfm>=1.0; extra == "dev"
+Dynamic: license-file

archgraph_mcp-1.0.0/README.md

@@ -0,0 +1,394 @@
+# ArchGraph MCP
+
+[![Tests](https://github.com/mustafa-zidan/archgraph-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/mustafa-zidan/archgraph-mcp/actions/workflows/test.yml)
+[![PyPI version](https://img.shields.io/pypi/v/archgraph-mcp.svg)](https://pypi.org/project/archgraph-mcp/)
+[![Python versions](https://img.shields.io/pypi/pyversions/archgraph-mcp.svg)](https://pypi.org/project/archgraph-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+ArchGraph MCP turns a repository into a queryable graph. It parses TypeScript, Java, and Kotlin source with
+[Tree-sitter](https://tree-sitter.github.io/), builds a directed graph of files, symbols, and dependencies, and exposes
+that graph to AI coding agents over the [Model Context Protocol](https://modelcontextprotocol.io/). Instead of grepping
+for call sites, an agent can ask what a function depends on, what breaks if it changes, or how two nodes connect.
+
+## How a repository becomes a queryable graph
+
+```
+Repository
+   ↓
+File Scanner (lazy, generator-based)
+   ↓
+Parser Layer (Tree-sitter: TypeScript, Java, Kotlin)
+   ↓
+Graph Builder (NetworkX DiGraph)
+   ↓
+Kuzu Storage (embedded graph DB + full-text search)
+   ↓
+Query Engine (BFS, shortest path, impact analysis)
+   ↓
+MCP Server (FastMCP: stdio, sse, or streamable-http transport)
+   ↓
+AI Agent (Cursor, Windsurf, Claude Code, etc.)
+```
+
+The graph itself lives in **NetworkX** at query time; traversals (BFS, shortest path, impact analysis) run in memory
+against that structure. **Kuzu**'s job is persistence and lexical search: it stores nodes and edges across restarts and
+powers BM25-style `search_nodes`, falling back to substring matching when full-text search finds nothing. Semantic
+search is a separate, optional layer: embedding vectors live in NumPy files next to the Kuzu path rather than inside the
+graph database itself.
+
+## Documentation
+
+This README covers installation, usage, and the reference tables. Three guides go deeper:
+
+- [Setup and MCP](docs/setup-and-mcp.md): install, first-time analyze, environment variables, stdio vs HTTP, Claude
+  Desktop, Cursor, VS Code, remote URLs, Docker, troubleshooting.
+- [Local build and semantic](docs/local-build-and-semantic.md): developing from a clone, `analyze --semantic-index`,
+  embedding backends, and serving with the vector index.
+- [Release cycle](docs/release-cycle.md): versioning and PyPI releases for maintainers.
+
+## Installing it
+
+`uvx archgraph-mcp` works once the package is on PyPI. Until the first release ships, install from a clone.
+
+### From PyPI, with uvx
+
+[`uvx`](https://docs.astral.sh/uv/guides/tools/) runs the published tool in an isolated environment, no global install
+needed:
+
+```bash
+uvx archgraph-mcp --help
+```
+
+The optional **`[semantic]`** extra pulls in NumPy for `search_nodes_semantic` and the vector index. Pass it with
+`--with` so the tool environment includes it:
+
+```bash
+uvx --with "archgraph-mcp[semantic]" archgraph-mcp --help
+```
+
+### From a git clone
+
+```bash
+git clone https://github.com/mustafa-zidan/archgraph-mcp.git
+cd archgraph-mcp
+uv sync --extra dev --extra semantic
+uv run archgraph-mcp --help
+```
+
+Drop `--extra semantic` if you don't need vector search; the core graph and full-text search work without it.
+
+## Analyzing and serving a repository
+
+Examples below use `uvx` (PyPI). From a clone, replace `uvx …` with `uv run …`.
+
+### Analyze
+
+```bash
+uvx archgraph-mcp analyze ./your-repo
+```
+
+This scans the repo, parses it, and writes a Kuzu database (`archgraph.kuzu` by default). Add `--semantic-index` to also
+build the vector index, which needs `[semantic]` in the environment:
+
+```bash
+uvx --with "archgraph-mcp[semantic]" archgraph-mcp analyze ./your-repo --semantic-index
+```
+
+### Serve over stdio (local)
+
+Most desktop agents spawn the process and talk over stdin/stdout:
+
+```bash
+uvx archgraph-mcp serve ./your-repo
+```
+
+With semantic tooling available to the server process:
+
+```bash
+uvx --with "archgraph-mcp[semantic]" archgraph-mcp serve ./your-repo
+```
+
+### Serve over HTTP (remote)
+
+```bash
+uvx archgraph-mcp serve ./your-repo --transport streamable-http --port 3847
+```
+
+### Graph viewer (HTTP transports only)
+
+`--graph-ui` (or `GRAPH_UI=1`) exposes a [vis-network](https://visjs.github.io/vis-network/docs/network/) view at
+`/graph` and raw JSON at `/api/graph` (optional `limit` query param, default `500`, caps node count for responsiveness).
+It's ignored under `stdio`, since there's no HTTP server to attach it to.
+
+```bash
+uvx archgraph-mcp serve ./your-repo --transport streamable-http --port 3847 --graph-ui
+```
+
+## Wiring it into an MCP client
+
+Full walkthroughs for Claude Desktop, Cursor, VS Code, and remote URLs are in
+[docs/setup-and-mcp.md](docs/setup-and-mcp.md). Quick reference below; it requires `uv` on `PATH` so `uvx` resolves.
+
+**Core** (lexical `search_nodes` only):
+
+```json
+{
+  "mcpServers": {
+    "archgraph": {
+      "command": "uvx",
+      "args": [
+        "archgraph-mcp",
+        "serve",
+        "/absolute/path/to/your/repo"
+      ]
+    }
+  }
+}
+```
+
+**With `[semantic]`** (NumPy + `search_nodes_semantic`, once an index exists):
+
+```json
+{
+  "mcpServers": {
+    "archgraph": {
+      "command": "uvx",
+      "args": [
+        "--with",
+        "archgraph-mcp[semantic]",
+        "archgraph-mcp",
+        "serve",
+        "/absolute/path/to/your/repo"
+      ]
+    }
+  }
+}
+```
+
+**From a git clone** (before a PyPI release, or for development):
+
+```json
+{
+  "mcpServers": {
+    "archgraph": {
+      "command": "uv",
+      "args": [
+        "run",
+        "--directory",
+        "/absolute/path/to/archgraph-mcp",
+        "archgraph-mcp",
+        "serve",
+        "/absolute/path/to/your/repo"
+      ]
+    }
+  }
+}
+```
+
+Run `uv sync --extra dev --extra semantic` in that clone before starting the MCP client.
+
+Optional env, e.g. a custom Kuzu path:
+
+```json
+{
+  "mcpServers": {
+    "archgraph": {
+      "command": "uvx",
+      "args": [
+        "archgraph-mcp",
+        "serve",
+        "/path/to/repo"
+      ],
+      "env": {
+        "ARCHGRAPH_STORE": "/path/to/repo/.archgraph/archgraph.kuzu"
+      }
+    }
+  }
+}
+```
+
+**Remote server** (streamable-http / SSE):
+
+```json
+{
+  "mcpServers": {
+    "archgraph": {
+      "url": "http://your-server:3847/mcp"
+    }
+  }
+}
+```
+
+Start the process itself with `uvx archgraph-mcp serve /repo --transport streamable-http --port 3847` (Docker
+instructions below).
+
+## The tools it exposes
+
+| Tool                    | Description                                       |
+| ----------------------- | ------------------------------------------------- |
+| `search_nodes`          | Lexical search (FTS + substring fallback) by type |
+| `search_nodes_semantic` | Cosine similarity (requires `[semantic]` + index) |
+| `trace_dependencies`    | What does this node depend on?                    |
+| `trace_dependents`      | What depends on this node?                        |
+| `impact_analysis`       | What breaks if this node changes?                 |
+| `trace_path`            | Shortest path between two nodes                   |
+| `architecture_summary`  | High-level graph summary                          |
+
+Node ids follow a `type:identifier` shape, e.g. `function:auth.loginUser` or `file:src/auth.ts`. Run `search_nodes`
+first if you don't know the exact id.
+
+```
+search_nodes(query="login", node_type="function")
+impact_analysis(node_id="function:auth.loginUser")
+trace_path(source_id="file:src/auth.ts", target_id="database:users")
+architecture_summary()
+```
+
+## Semantic search
+
+Lexical search (`search_nodes`) matches names and text. Semantic search (`search_nodes_semantic`) matches meaning, at
+the cost of an embedding backend and a build step.
+
+1. Install `[semantic]` into the tool environment:
+   `uvx --with "archgraph-mcp[semantic]" archgraph-mcp analyze ./repo --semantic-index` (or `uv sync --extra semantic`
+   from a clone).
+2. Pick a backend via `ARCHGRAPH_EMBED_BACKEND`:
+   - `openai` (default): `POST {OPENAI_BASE_URL}/v1/embeddings`. Works against LM Studio, Ollama's OpenAI-compatible
+     mode, or OpenAI itself.
+   - `local`: in-process models via `sentence-transformers`, installed separately (
+     `pip install sentence-transformers`).
+3. Build the index during analyze, with the flag or the env var: `archgraph-mcp analyze ./repo --semantic-index` or
+   `ARCHGRAPH_BUILD_SEMANTIC_INDEX=1`. This writes `archgraph.vectors.npz` and `archgraph.embeddings.json` next to the
+   Kuzu file (`--store` / `ARCHGRAPH_STORE`).
+
+| Variable                      | Purpose                                                                                                                                                                                                          |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ARCHGRAPH_EMBED_BACKEND`     | `openai` or `local`                                                                                                                                                                                              |
+| `ARCHGRAPH_EMBED_BATCH_SIZE`  | OpenAI HTTP backend: inputs per request (default `64`). If the server returns fewer vectors than inputs, the client retries one string per request automatically; set `1` to skip the slow failed-batch attempt. |
+| `OPENAI_BASE_URL`             | e.g. `http://127.0.0.1:1234/v1` for LM Studio                                                                                                                                                                    |
+| `OPENAI_API_KEY`              | Bearer token (dummy value is fine if the server ignores it)                                                                                                                                                      |
+| `OPENAI_EMBEDDING_MODEL`      | Model id for `/v1/embeddings`                                                                                                                                                                                    |
+| `ARCHGRAPH_LOCAL_EMBED_MODEL` | Sentence-transformers model id when backend is `local`                                                                                                                                                           |
+
+The index build and the query-time call must agree on backend and model; a mismatch produces vectors that don't line up,
+not an error.
+
+## Supported languages
+
+- TypeScript / TSX
+- Java
+- Kotlin (`.kt`, `.kts`)
+
+## Version support
+
+Requires Python 3.12+ (`requires-python` in [`pyproject.toml`](pyproject.toml)). CI
+([`.github/workflows/test.yml`](.github/workflows/test.yml)) runs this matrix on every push:
+
+| OS      | 3.12 | 3.13 | 3.14                   |
+| ------- | ---- | ---- | ---------------------- |
+| Linux   | ✅   | ✅   | ✅                     |
+| macOS   | ✅   | ✅   | ✅ (built from source) |
+| Windows | ✅   | ✅   | ❌ see note below      |
+
+Windows + Python 3.14 is excluded from CI. [`kuzu`](https://pypi.org/project/kuzu/#files) 0.11.3 ships a `cp314` wheel
+for Linux but not for Windows or macOS, so both fall back to a source build. macOS's build succeeds because Xcode's
+command line tools provide `make`; the Windows runner has no such toolchain, so the same fallback fails there. It's an
+upstream packaging gap, not something this project controls. Docker sidesteps it entirely, since the container is
+Linux-based regardless of host OS.
+
+## Running it as a service
+
+### Docker
+
+```bash
+docker build -t archgraph-mcp .
+docker run -p 3847:3847 -v /path/to/repo:/repo archgraph-mcp
+```
+
+### Railway
+
+1. Connect the GitHub repo at [railway.app](https://railway.app).
+2. Set the environment variable `REPO_PATH=/repo`.
+3. Deploy; Railway picks up `railway.json` automatically.
+
+### Fly.io
+
+```bash
+fly launch
+fly deploy
+```
+
+## Environment variables
+
+| Variable                         | Default          | Description                                                                                          |
+| -------------------------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
+| `REPO_PATH`                      | `.`              | Path to the repository to analyze                                                                    |
+| `ARCHGRAPH_STORE`                | `archgraph.kuzu` | Kuzu database path (overrides the default when the CLI does not pass `--store`)                      |
+| `PORT`                           | `3847`           | Port for SSE transport                                                                               |
+| `MCP_TRANSPORT`                  | `stdio`          | Transport mode: `stdio`, `sse`, or `streamable-http`                                                 |
+| `GRAPH_UI`                       | unset            | Set to `1` / `true` to enable `/graph` and `/api/graph` (same as `--graph-ui`; HTTP transports only) |
+| `ARCHGRAPH_BUILD_SEMANTIC_INDEX` | unset            | Set to `1` / `true` to build the vector index when serving triggers a full analyze (optional)        |
+
+## Developing on it
+
+```bash
+uv sync --extra dev
+# or: pip install -e ".[dev]"
+```
+
+Lint and format:
+
+```bash
+ruff check src tests
+ruff format src tests
+```
+
+Markdown (see [`.mdformat.toml`](.mdformat.toml); [GFM](https://github.github.com/gfm/) tables and wrapping):
+
+```bash
+mdformat README.md CHANGELOG.md docs/
+mdformat --check README.md CHANGELOG.md docs/
+```
+
+Static typing:
+
+```bash
+mypy src
+```
+
+Tests:
+
+```bash
+pytest tests/ -v
+```
+
+Optional [pre-commit](https://pre-commit.com/) hooks run Ruff lint and format on commit:
+
+```bash
+pip install pre-commit
+pre-commit install
+```
+
+## Releasing to PyPI
+
+[`.github/workflows/test.yml`](.github/workflows/test.yml) runs on every push and PR to `main`, `master`, or `develop`:
+`uv sync --extra dev`, Ruff, mdformat, mypy, and pytest, across Ubuntu, macOS, and Windows on Python 3.12, 3.13, and
+3.14.
+
+[`.github/workflows/release.yml`](.github/workflows/release.yml) is manual (`workflow_dispatch`) and publishes to
+[PyPI](https://pypi.org/p/archgraph-mcp) via [trusted publishing](https://docs.pypi.org/trusted-publishers/) (OIDC, no
+long-lived token). To cut a release:
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml) and add a matching section to [`CHANGELOG.md`](CHANGELOG.md),
+   then merge to the default branch.
+2. One-time setup: on PyPI, add a trusted publisher for this repo (workflow `release.yml`, environment `pypi`); on
+   GitHub, create an environment named `pypi`.
+3. Run **Actions → Release → Run workflow**, entering the same version string as in `pyproject.toml`.
+
+The workflow tags `vX.Y.Z`, builds with `uv build`, publishes to PyPI, signs the artifacts with Sigstore, and creates a
+GitHub Release with notes pulled from the changelog. Full maintainer guide:
+[docs/release-cycle.md](docs/release-cycle.md).
+
+## License
+
+MIT, see [LICENSE](LICENSE).

archgraph_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,79 @@
+[build-system]
+requires = ["setuptools>=80.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "archgraph-mcp"
+version = "1.0.0"
+description = "MCP server that builds a knowledge graph of a software codebase"
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.13.4",
+    "networkx>=3.6.1",
+    "mcp>=1.28.1,<2.0",
+    "uvicorn>=0.51.0",
+    "starlette>=1.3.1",
+    "tree-sitter>=0.26.0",
+    "tree-sitter-typescript>=0.23.2",
+    "tree-sitter-java>=0.23.5",
+    "tree-sitter-kotlin>=1.1.0",
+    "kuzu>=0.11.3",
+]
+
+[project.optional-dependencies]
+semantic = [
+    "numpy>=2.5.1",
+]
+dev = [
+    "pytest>=9.1.1",
+    "pytest-asyncio>=1.4.0",
+    "ruff>=0.15.22",
+    "mypy>=2.3.0",
+    "types-networkx>=3.6.1.20260624",
+    "mdformat>=1.0",
+    "mdformat-gfm>=1.0",
+]
+
+[project.scripts]
+archgraph-mcp = "archgraph_mcp.__main__:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
+[tool.ruff]
+target-version = "py312"
+line-length = 120
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["archgraph_mcp"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.mypy]
+python_version = "3.12"
+mypy_path = "src"
+packages = ["archgraph_mcp"]
+warn_return_any = false
+warn_unused_configs = true
+disallow_untyped_defs = false
+check_untyped_defs = true
+
+[[tool.mypy.overrides]]
+module = [
+    "tree_sitter.*",
+    "tree_sitter_typescript.*",
+    "tree_sitter_java.*",
+    "tree_sitter_kotlin.*",
+    "kuzu.*",
+    "numpy.*",
+    "sentence_transformers.*",
+]
+ignore_missing_imports = true

archgraph_mcp-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

archgraph_mcp-1.0.0/src/archgraph_mcp/__init__.py

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

archgraph_mcp-1.0.0/src/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))