orgraph-mcp 0.1.0__tar.gz

orgraph_mcp-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,178 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: read
+
+jobs:
+  plan-release:
+    name: Plan release
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.version.outputs.version }}
+      tag: ${{ steps.version.outputs.tag }}
+      should_release: ${{ steps.check.outputs.should_release }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Read package version
+        id: version
+        run: |
+          python - <<'PY'
+          import tomllib
+          from pathlib import Path
+          data = tomllib.loads(Path("pyproject.toml").read_text())
+          version = data["project"]["version"]
+          tag = f"v{version}"
+          github_output = Path(__import__("os").environ["GITHUB_OUTPUT"])
+          with github_output.open("a") as fh:
+              fh.write(f"version={version}\n")
+              fh.write(f"tag={tag}\n")
+          PY
+
+      - name: Check whether tag already exists
+        id: check
+        run: |
+          if git ls-remote --exit-code --tags origin "refs/tags/${{ steps.version.outputs.tag }}" >/dev/null 2>&1; then
+            echo "should_release=false" >> "$GITHUB_OUTPUT"
+            echo "Tag ${{ steps.version.outputs.tag }} already exists — skipping."
+          else
+            echo "should_release=true" >> "$GITHUB_OUTPUT"
+            echo "Tag ${{ steps.version.outputs.tag }} is new — releasing."
+          fi
+
+  build:
+    name: Build distributions
+    runs-on: ubuntu-latest
+    needs: plan-release
+    if: needs.plan-release.outputs.should_release == 'true'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build package
+        run: uv build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: release-dists
+          path: dist/*
+
+  publish-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: [plan-release, build]
+    if: needs.plan-release.outputs.should_release == 'true'
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  create-release:
+    name: Create GitHub release
+    runs-on: ubuntu-latest
+    needs: [plan-release, publish-pypi]
+    if: needs.plan-release.outputs.should_release == 'true'
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: release-dists
+          path: dist
+
+      - name: Extract release notes from CHANGELOG.md
+        id: notes
+        env:
+          RELEASE_VERSION: ${{ needs.plan-release.outputs.version }}
+        run: |
+          python - <<'PY'
+          import os, re
+          from pathlib import Path
+          version = os.environ["RELEASE_VERSION"]
+          changelog = Path("CHANGELOG.md")
+          out = Path(os.environ["RUNNER_TEMP"]) / "release-notes.md"
+          github_output = Path(os.environ["GITHUB_OUTPUT"])
+          if not changelog.exists():
+              github_output.open("a").write("has_notes=false\n")
+              raise SystemExit(0)
+          heading = re.compile(
+              rf"^##\s+(?:\[?v?{re.escape(version)}\]?)(?:\s+-\s+.+)?\s*$"
+          )
+          next_h = re.compile(r"^##\s+")
+          lines = changelog.read_text().splitlines()
+          start = None
+          for i, l in enumerate(lines):
+              if heading.match(l.strip()):
+                  start = i + 1
+                  break
+          if start is None:
+              github_output.open("a").write("has_notes=false\n")
+              raise SystemExit(0)
+          end = len(lines)
+          for i in range(start, len(lines)):
+              if next_h.match(lines[i].strip()):
+                  end = i
+                  break
+          body = "\n".join(lines[start:end]).strip()
+          if not body:
+              github_output.open("a").write("has_notes=false\n")
+              raise SystemExit(0)
+          out.write_text(body + "\n")
+          with github_output.open("a") as fh:
+              fh.write("has_notes=true\n")
+              fh.write(f"notes_file={out}\n")
+          PY
+
+      - name: Create git tag
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git tag "${{ needs.plan-release.outputs.tag }}" "${{ github.sha }}"
+          git push origin "${{ needs.plan-release.outputs.tag }}"
+
+      - name: Create GitHub release (with CHANGELOG notes)
+        if: steps.notes.outputs.has_notes == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ needs.plan-release.outputs.tag }}" dist/* \
+            --target "${{ github.sha }}" \
+            --title "${{ needs.plan-release.outputs.tag }}" \
+            --notes-file "${{ steps.notes.outputs.notes_file }}"
+
+      - name: Create GitHub release (auto-generated notes)
+        if: steps.notes.outputs.has_notes != 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "${{ needs.plan-release.outputs.tag }}" dist/* \
+            --target "${{ github.sha }}" \
+            --title "${{ needs.plan-release.outputs.tag }}" \
+            --generate-notes

orgraph_mcp-0.1.0/.gitignore

@@ -0,0 +1,24 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual env
+.venv/
+
+# Test cache
+.pytest_cache/
+
+# orgraph runtime state (per-repo, not source)
+.orgraph/
+
+# Reference code repos (not our source)
+.codes/
+
+# Editor
+.DS_Store
+*.swp
+.codes/

orgraph_mcp-0.1.0/AGENTS.md

@@ -0,0 +1,133 @@
+# AGENTS.md — orgraph
+
+Authoritative agent guide for the orgraph codebase. Read this before making changes.
+
+## Current version: 0.1.0
+
+## What orgraph does
+
+Points at any repo → builds a persistent Kuzu knowledge graph + topology clusters + Leiden communities → serves it via MCP so coding agents (Cursor, Claude CLI, Codex) can query architectural context.
+## Project Snapshot
+
+T3 Code is a minimal web GUI for using coding agents like Codex and Claude.
+
+This repository is a VERY EARLY WIP. Proposing sweeping changes that improve long-term maintainability is encouraged.
+
+## Core Priorities
+
+1. Performance first.
+2. Reliability first.
+3. Keep behavior predictable under load and during failures (session restarts, reconnects, partial streams).
+
+If a tradeoff is required, choose correctness and robustness over short-term convenience.
+## Maintainability
+
+
+Long term maintainability is a core priority. If you add new functionality, first check if there is shared logic that can be extracted to a separate module. Duplicate logic across multiple files is a code smell and should be avoided. Don't be afraid to change existing code. Don't take shortcuts by just adding local logic to solve a problem.
+#Reference Docs 
+.codes directory contain reference repo 
+
+Use these as implementation references when designing protocol handling, UX flows, and operational safeguards.
+
+
+## Phase status
+
+| Phase | Status | Notes |
+|---|---|---|
+| P1 Foundation + Extraction | ✅ COMPLETE | `orgraph index` + `orgraph status` working, 21 tests pass |
+| P2 Topology + Communities | ✅ COMPLETE | BFS clusters + Leiden communities wired into `orgraph index` and `orgraph status` |
+| P3 Search | ✅ COMPLETE | `orgraph search` works; semble BM25+Model2Vec; 9 tests |
+| P4 MCP Server | ✅ COMPLETE | FastMCP stdio, 5 tools, 12 tests |
+| P5 Eval Harness | ✅ COMPLETE | NDCG@10=0.903, MRR=0.895 on codewiki (target >0.70); 17 tests |
+
+## Package layout
+
+```
+orgraph/
+  cli.py                  # Click CLI: index / status / search / serve
+  extract/
+    types.py              # NodeDict, EdgeDict, ExtractionResult, make_uid()
+    manifest.py           # Manifest — file → md5 tracking (.orgraph/manifest.json)
+    scip.py               # ScipExtractor — compiler-accurate, falls back to None
+    scip_pb2.py           # Auto-generated protobuf bindings (SCIP format)
+    treesitter.py         # TreeSitterExtractor — wraps graphify; _GRAPHIFY_ROOT must exist
+  graph/
+    kuzu.py               # OrgraphDB — thin Kuzu wrapper; do NOT mkdir db_path itself
+    schema.py             # create_schema(db) — all node/edge tables (IF NOT EXISTS)
+    builder.py            # GraphBuilder.ingest(result) → (nodes, edges) written
+  topology/
+    call_graph.py         # CallGraph, CallEdge, GraphRelation data structures
+    context.py            # RepoContext shim; build_repo_context(result, repo_path)
+    topology.py           # build_topology_map(ctx) → TopologyMap (BFS clusters)
+    cluster.py            # cluster(G) → Leiden communities; build_nx_graph_from_result()
+    serialise.py          # save/load topology.json and communities.json
+  search/
+    index.py              # SearchIndex stub (P3)
+  mcp/
+    server.py             # start_server() stub (P4)
+  eval/
+    __init__.py           # empty (P5)
+```
+
+## State written to indexed repos
+
+```
+<repo>/.orgraph/
+  graph.kuzu        # Kuzu DB (single file)
+  manifest.json     # file → md5
+  topology.json     # TopologyMap serialised
+  communities.json  # Leiden {community_id: [node_uids]}
+```
+
+## Architecture invariants
+
+- **Kuzu DB path**: Kuzu creates its own structure at `db_path`. Never `mkdir(db_path)` — only `mkdir(db_path.parent)`. Fixed in `graph/kuzu.py`.
+- **graphify path**: `extract/treesitter.py` adds `~/tss/codegen/orgraph/.codes/graphify` to `sys.path` at runtime. If `.codes/` moves, update `_GRAPHIFY_ROOT`.
+- **graphify label field**: graphify puts display names in `label` (`"authenticate()"`, `"User"`). Not a type tag. Conversion logic lives in `treesitter.py`.
+- **tree-sitter grammars**: `tree-sitter-python`, `tree-sitter-javascript`, `tree-sitter-typescript` must be installed (in `pyproject.toml` deps).
+- **`_is_test_file` heuristic**: Files under paths containing `/tests/` or `/test/` are excluded from BFS entry points. Tests that run topology on fixture code must copy fixtures to a non-tests temp dir (`shutil.copytree(FIXTURE, tmp_path / "simple_python")`).
+- **Topology depends on ExtractionResult**: `build_repo_context()` builds CallGraph directly from ExtractionResult CALLS edges, not from Kuzu. Topology runs before DB is closed.
+- **Leiden falls back to Louvain**: If `graspologic` is not installed, networkx Louvain is used. Both give stable results via seed=42.
+
+## CLI commands
+
+```bash
+orgraph index <repo>     # extract → kuzu → topology → leiden → save
+orgraph status <repo>    # node/edge counts + cluster table + community count
+orgraph search <q> <r>   # search (P3 stub)
+orgraph serve <repo>     # MCP server (P4 stub)
+```
+
+## Testing
+
+```bash
+cd ~/tss/codegen/orgraph
+uv run python -m pytest tests/ -q    # all 21 tests
+uv run python -m pytest tests/test_extract.py tests/test_graph.py -q   # P1 only
+uv run python -m pytest tests/test_topology.py -q                       # P2 only
+```
+
+## Reference repos (all at `~/tss/codegen/orgraph/.codes/`)
+
+| Repo | What we borrow |
+|---|---|
+| `CodeGraphContext` | SCIP extractor, Kuzu adapter, graph schema, scip_pb2.py |
+| `graphify` | tree-sitter extractor, Leiden cluster.py |
+| `semble` | pip dep only — hybrid BM25+Model2Vec search |
+| `codewiki` (`~/tss/codegen/codewiki`) | CallGraph data structures, BFS topology clustering |
+
+## Next phase: P5 — Eval Harness
+
+Build `orgraph/eval/` with:
+- `ground_truth.py` — `EvalQuery` dataclass (query, relevant_files, relevant_symbols, query_type)
+- `metrics.py` — `ndcg_at_k()`, `mrr()`, `precision_at_k()`
+- `runner.py` — `EvalRunner(repo_path, ground_truth_path).run() → EvalReport`
+- `fixtures/codewiki_gt.json` — 20+ ground-truth Q&A pairs for codewiki
+- CLI: `orgraph eval <repo> --ground-truth <path>`
+- Target: NDCG@10 > 0.70 on codewiki
+
+## MCP tool notes (P4)
+
+- `register_tools(mcp, db, idx, topology, communities, repo_path)` returns `dict[str, Callable]` — use this in tests, don't introspect FastMCP internals
+- FastMCP 3.4.2: `list_tools()` is async, `get_tool(name)` is async — bypass both by using the returned dict
+- Tool functions are defined as closures over `db`, `idx`, `topology`, `communities`, `repo_path`

orgraph_mcp-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## 0.1.0 - 2025-06-17
+
+### Added
+- `orgraph index` — extract nodes/edges via tree-sitter (SCIP fallback), build topology clusters, Leiden communities, and hybrid search index
+- `orgraph status` — show graph stats, topology clusters, and community sizes
+- `orgraph search` — hybrid BM25+semantic code search
+- `orgraph serve` — FastMCP stdio server with 6 tools: `search`, `trace`, `get_context`, `find_entry_points`, `get_dependencies`, `reindex`
+- `orgraph eval` — retrieval eval harness with NDCG@10, MRR, Precision@k
+- `orgraph install` / `orgraph uninstall` — interactive installer for Claude Code, Cursor, Codex, VS Code, Gemini CLI, Opencode
+- Auto-index on `serve` — no manual `orgraph index` needed on first run
+- Incremental `reindex` MCP tool — detects changed/deleted files via md5 manifest, re-extracts only what changed, swaps state live without server restart
+- Fully vendored graphify extractor — standalone install, no external path dependencies

orgraph_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pranav Kumar
+
+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.

orgraph_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: orgraph-mcp
+Version: 0.1.0
+Summary: Codebase knowledge graph MCP server — call chains, topology, and hybrid search for coding agents
+Project-URL: Homepage, https://github.com/tss-pranavkumar/orgraph
+Project-URL: Repository, https://github.com/tss-pranavkumar/orgraph
+Project-URL: Bug Tracker, https://github.com/tss-pranavkumar/orgraph/issues
+Author-email: Pranav Kumar <pranav.kumar@thesouledstore.com>
+License: MIT
+License-File: LICENSE
+Keywords: agents,code-search,codebase,knowledge-graph,llm,mcp
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: fastmcp>=2.0
+Requires-Dist: kuzu>=0.8
+Requires-Dist: networkx>=3.4
+Requires-Dist: orjson>=3.9
+Requires-Dist: pathspec>=0.12
+Requires-Dist: protobuf<3.21,>=3.20
+Requires-Dist: questionary>=2.0
+Requires-Dist: rich>=13.0
+Requires-Dist: semble>=0.3.4
+Requires-Dist: tree-sitter-javascript>=0.23
+Requires-Dist: tree-sitter-python>=0.23
+Requires-Dist: tree-sitter-typescript>=0.23
+Requires-Dist: tree-sitter<0.26,>=0.23
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# orgraph
+
+Codebase knowledge graph for coding agents. Points at any repo, builds a persistent graph, serves it via MCP.
+
+## Install
+
+```bash
+uv venv && uv pip install -e .
+```
+
+## Usage
+
+```bash
+# Index a repo
+orgraph index /path/to/repo
+
+# Check graph stats
+orgraph status /path/to/repo
+
+# Search code
+orgraph search "authentication middleware" /path/to/repo
+
+# Start MCP server (add to Cursor / Claude CLI config)
+orgraph serve /path/to/repo
+```
+
+## MCP config (Claude CLI)
+
+```json
+{
+  "mcpServers": {
+    "orgraph": { "command": "orgraph", "args": ["serve", "."] }
+  }
+}
+```
+
+## Architecture
+
+See [plan](../.claude/plans/i-wnant-you-to-glowing-pelican.md) for full design.
+
+- **Extraction**: SCIP (compiler-accurate) → tree-sitter fallback (graphify)
+- **Storage**: Kuzu embedded graph DB
+- **Search**: semble hybrid BM25 + Model2Vec
+- **Topology**: codewiki BFS entry-point clustering
+- **Communities**: Leiden community detection (graphify)
+- **Agent interface**: FastMCP stdio server, 5 tools

orgraph_mcp-0.1.0/README.md

@@ -0,0 +1,46 @@
+# orgraph
+
+Codebase knowledge graph for coding agents. Points at any repo, builds a persistent graph, serves it via MCP.
+
+## Install
+
+```bash
+uv venv && uv pip install -e .
+```
+
+## Usage
+
+```bash
+# Index a repo
+orgraph index /path/to/repo
+
+# Check graph stats
+orgraph status /path/to/repo
+
+# Search code
+orgraph search "authentication middleware" /path/to/repo
+
+# Start MCP server (add to Cursor / Claude CLI config)
+orgraph serve /path/to/repo
+```
+
+## MCP config (Claude CLI)
+
+```json
+{
+  "mcpServers": {
+    "orgraph": { "command": "orgraph", "args": ["serve", "."] }
+  }
+}
+```
+
+## Architecture
+
+See [plan](../.claude/plans/i-wnant-you-to-glowing-pelican.md) for full design.
+
+- **Extraction**: SCIP (compiler-accurate) → tree-sitter fallback (graphify)
+- **Storage**: Kuzu embedded graph DB
+- **Search**: semble hybrid BM25 + Model2Vec
+- **Topology**: codewiki BFS entry-point clustering
+- **Communities**: Leiden community detection (graphify)
+- **Agent interface**: FastMCP stdio server, 5 tools

orgraph_mcp-0.1.0/orgraph/__init__.py

@@ -0,0 +1,3 @@
+"""orgraph — codebase knowledge graph for coding agents."""
+
+__version__ = "0.1.0"