code-context-mcp 1.0.0__py3-none-any.whl

code_context_mcp-1.0.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: code-context-mcp
+Version: 1.0.0
+Summary: MCP server with local RAG for Claude Code repo context
+Author: code-context contributors
+License: MIT
+Project-URL: Homepage, https://github.com/nachogeinfor-ops/code-context
+Project-URL: Documentation, https://github.com/nachogeinfor-ops/code-context#readme
+Project-URL: Issues, https://github.com/nachogeinfor-ops/code-context/issues
+Project-URL: Changelog, https://github.com/nachogeinfor-ops/code-context/blob/main/CHANGELOG.md
+Project-URL: Tool Protocol, https://github.com/nachogeinfor-ops/context-template/blob/main/docs/tool-protocol.md
+Keywords: claude-code,mcp,rag,developer-tools
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing :: Indexing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.0
+Requires-Dist: numpy>=1.26
+Requires-Dist: pyarrow>=14
+Requires-Dist: platformdirs>=4
+Requires-Dist: pathspec>=0.12
+Requires-Dist: filelock>=3.13
+Requires-Dist: sentence-transformers>=2.7
+Requires-Dist: tree-sitter>=0.22
+Requires-Dist: tree-sitter-language-pack>=0.7
+Provides-Extra: openai
+Requires-Dist: openai>=1.30; extra == "openai"
+Provides-Extra: watch
+Requires-Dist: watchdog>=4; extra == "watch"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: ruff>=0.5; extra == "dev"
+Requires-Dist: watchdog>=4; extra == "dev"
+Dynamic: license-file
+
+# code-context
+
+[![PyPI](https://img.shields.io/pypi/v/code-context-mcp.svg)](https://pypi.org/project/code-context-mcp/)
+[![CI](https://github.com/nachogeinfor-ops/code-context/actions/workflows/ci.yml/badge.svg)](https://github.com/nachogeinfor-ops/code-context/actions/workflows/ci.yml)
+[![Python](https://img.shields.io/pypi/pyversions/code-context-mcp.svg)](https://pypi.org/project/code-context-mcp/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Status: stable (v1.0.0).** A Python MCP server with local RAG
+> for [Claude Code](https://docs.claude.com/claude-code).
+> Implements the [`code-context` Tool Protocol](https://github.com/nachogeinfor-ops/context-template/blob/main/docs/tool-protocol.md)
+> v1.2 defined by [`context-template`](https://github.com/nachogeinfor-ops/context-template).
+
+## What it does
+
+When you point Claude Code at a repo, you give it `CLAUDE.md` for static context. `code-context` adds **dynamic context** via 7 MCP tools:
+
+- **`search_repo(query, top_k?, scope?)`** — **hybrid retrieval** across the codebase: vector embeddings (semantic) fused with BM25 keyword search (exact identifiers) via Reciprocal Rank Fusion. Optional cross-encoder reranking (off by default — enable with `CC_RERANK=on`).
+- **`recent_changes(since?, paths?, max?)`** — recent git commits, optionally filtered.
+- **`get_summary(scope?, path?)`** — structured project summary (name, stack, key modules, stats).
+- **`find_definition(name, language?, max?)`** — locate where a symbol (function, class, method, type) is defined. Use INSTEAD of `Grep` for `def X` / `class X` / `function X` patterns. Returns repo-relative paths with line ranges and the symbol's kind (function, class, method, interface, struct, enum, record).
+- **`find_references(name, max?)`** — list every line mentioning a named symbol. Use INSTEAD of `grep -n "X"` when the user asks "who calls X?" or "where is X used?". Word-boundary matched, so `log` doesn't return `logger`.
+- **`get_file_tree(path?, max_depth?, include_hidden?)`** — repo-relative directory tree, gitignore-aware. Use INSTEAD of `Bash: ls -R` or `Bash: tree` for orientation prompts ("show me the project structure", "what's in this module?"). Returns hierarchical FileTreeNode with file sizes; honors `.gitignore`; defaults to depth 4.
+- **`explain_diff(ref, max_chunks?)`** — AST-aligned chunks affected by the diff at `ref` (full SHA, `HEAD`, `HEAD~N`, branch). Use INSTEAD of `Bash: git show <sha>` for "what does this commit do" questions. The chunker resolves which whole functions/classes were touched, not raw line additions.
+
+Architecture: hexagonal (ports & adapters). 9 driven ports with default implementations (sentence-transformers embeddings, NumPy+Parquet vector store, tree-sitter / line chunker, filesystem code source, git CLI, filesystem introspector, SQLite FTS5 keyword index, cross-encoder reranker, SQLite-backed symbol index). All swappable.
+
+## Install
+
+```bash
+pip install code-context-mcp
+# or, if you don't want torch (~2 GB), use the OpenAI embeddings backend:
+pip install code-context-mcp[openai]
+```
+
+> The PyPI distribution is **`code-context-mcp`** (the unhyphenated `code-context` name was squatted by an unrelated, abandoned project from 2023; see CHANGELOG for context). The Python module is still `code_context` and the CLI binaries are still `code-context` and `code-context-server`, so quickstart commands and `from code_context import ...` are unchanged.
+
+> Note: the default install pulls `sentence-transformers` + the `all-MiniLM-L6-v2` model on first run. Plan for ~2 GB of disk after first reindex (torch ≈ 2 GB, model ≈ 90 MB). Use the `[openai]` extra to avoid torch entirely.
+
+## Quickstart
+
+```bash
+cd /path/to/your/repo
+claude mcp add code-context --command code-context-server
+# Open Claude Code. From v0.9.0 the server starts in <1 s on a previously-indexed
+# repo; the first reindex (and any subsequent ones) run on a background thread,
+# so queries are never blocked. Cold start: queries return [] until the first
+# bg reindex completes (~30-60 s on a typical repo with all-MiniLM on CPU).
+# Edit-cycle reindex is sub-10 s thanks to v0.8.0's dirty_set tracking.
+```
+
+### Live mode (optional)
+
+If you want every save in the repo to flow into the index without
+manual `code-context reindex`:
+
+```bash
+pip install code-context-mcp[watch]   # adds watchdog
+export CC_WATCH=on
+claude mcp add code-context --command code-context-server
+```
+
+Edits are debounced for ~1 s (configurable via
+`CC_WATCH_DEBOUNCE_MS`) and then trigger a background reindex.
+Default off — opt-in.
+
+For OpenAI embeddings:
+```bash
+export CC_EMBEDDINGS=openai
+export OPENAI_API_KEY=sk-...
+claude mcp add code-context --command code-context-server
+```
+
+## Making Claude actually use these tools
+
+Claude Code defaults to its built-in tools (`Bash`, `Grep`, `Glob`, `Read`) over MCP servers because it knows them best. To get the value of `code-context`, give Claude an explicit hint by adding a section like this to your project's `CLAUDE.md`:
+
+```markdown
+## Context tools
+
+This repo has the [code-context](https://github.com/nachogeinfor-ops/code-context) MCP server installed. Prefer it over built-in tools:
+
+- **`search_repo(query, top_k?, scope?)`** — for conceptual questions like "where do we handle authentication" or "how is caching implemented". Use this instead of `Grep` whenever the query isn't an exact string match.
+- **`recent_changes(since?, paths?, max?)`** — for "what changed recently" / commit-history questions. Use this instead of shelling out to `git log`.
+- **`get_summary(scope?, path?)`** — for project orientation at session start, or to inspect a specific module.
+- **`find_definition(name, language?, max?)`** — for "where is X defined?". Use this instead of `Grep` for `def X` / `class X` patterns; tree-sitter-indexed at reindex time, so it's faster and more accurate than scanning text.
+- **`find_references(name, max?)`** — for "who calls X?" / "where is X used?". Use this instead of `grep -n`; word-boundary matched so `log` won't match `logger`.
+- **`get_file_tree(path?, max_depth?, include_hidden?)`** — for "show me the project structure" / "what's in this module?". Use this instead of `Bash: ls -R` / `Bash: tree`; gitignore-aware and structured (file sizes included).
+- **`explain_diff(ref, max_chunks?)`** — for "what does this commit do?" / "what changed in HEAD~3?". Use this instead of `Bash: git show <sha>`; the chunker resolves whole functions/classes that were touched, not raw line additions.
+```
+
+Without this hint, Claude will work fine — it just won't reach for the MCP tools, which means the index goes unused. The hint is one paragraph; copy-paste it.
+
+## CLI
+
+`code-context-server` is the MCP binary; you don't run it directly. The companion `code-context` CLI helps administer the index:
+
+```bash
+code-context status              # print index health + dirty/deleted counts
+code-context reindex             # incremental by default (only changed files)
+code-context reindex --force     # full reindex (post-model-upgrade or cache reset)
+code-context query "where do we validate user emails"   # debug, no MCP
+code-context clear --yes         # delete the cache for this repo
+```
+
+## Configuration
+
+Configured via env vars. See [`docs/configuration.md`](docs/configuration.md) for the full list. Most-used:
+
+| Var | Default |
+|---|---|
+| `CC_EMBEDDINGS` | `local` (or `openai`) |
+| `CC_EMBEDDINGS_MODEL` | `all-MiniLM-L6-v2` |
+| `CC_INCLUDE_EXTENSIONS` | `.py,.js,.ts,.jsx,.tsx,.go,.rs,.java,.c,.cpp,.h,.hpp,.md,.yaml,.yml,.json` |
+| `CC_CHUNKER` | `treesitter` (AST-aware for Py/JS/TS/Go/Rust/C#, line fallback) — set `line` for v0.1.x behavior |
+| `CC_CACHE_DIR` | platformdirs user cache |
+
+## Documentation
+
+- **[Public API (v1)](docs/v1-api.md)** — what's stable; what's not. Read this before depending on `code-context` from another project.
+- **[Configuration](docs/configuration.md)** — every env var with examples (chunker strategies, hybrid search, symbol index, background reindex, watch mode, …).
+- **[Architecture](docs/architecture.md)** — hexagonal diagram, port contracts, indexing lifecycle, Sprint 7 background-thread + bus.
+- **[Eval suite](benchmarks/eval/README.md)** — NDCG@10 / MRR / latency baselines per retrieval mode.
+- **[Releasing](docs/release.md)** — Trusted Publisher setup, per-release checklist.
+- **[Extending](docs/extending.md)** — write your own embeddings provider, vector store, or chunker.
+
+## Status
+
+**v1.0.0 — stable.** Public surface frozen; v1.x will only add. See
+[`docs/v1-api.md`](docs/v1-api.md) for the commitment scope and
+[`CHANGELOG.md`](CHANGELOG.md) for what shipped in each version.
+
+## License
+
+[MIT](LICENSE).

code_context_mcp-1.0.0.dist-info/RECORD

@@ -0,0 +1,43 @@
+code_context/__init__.py,sha256=gJtH71A7AD6NuyaIrjnywBvecuMItchx8MYKHY_Kh7M,99
+code_context/_background.py,sha256=rWKvjh5TmDXuLLgCm13UPJoDqTdbJoE62wwLMPC0JYg,3444
+code_context/_composition.py,sha256=OMaXJBKJvo8TULmaO388lJwVk1MHvgdB7xCua8-Mbfg,14571
+code_context/_watcher.py,sha256=Mv3XpKcAHJYf4s3oyAvVLD3ikupHJ__Cd-KYzpb292Q,2999
+code_context/cli.py,sha256=EzUJpt0uTmOvlumV1Id5oyIAoeCLC_6UnfG3Iu2dK-4,5408
+code_context/config.py,sha256=jtTzuFHkWqU757gvNkih07W7zkFeejpoXZ35C_kJSOo,3911
+code_context/server.py,sha256=ZVROU7kobXghplldTQosiTAjh22r6VWO7HtTr2EoKF8,5106
+code_context/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_context/adapters/driven/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_context/adapters/driven/chunker_dispatcher.py,sha256=aRNRhuxyWdj6dU3bcPA6386IV-4Has2US25cC_Q3gpo,1522
+code_context/adapters/driven/chunker_line.py,sha256=6X2S3R60YHuj1PJ7wGz7nMfokpHGknfhL7Jg5SQFn9c,1493
+code_context/adapters/driven/chunker_treesitter.py,sha256=RgYbUZdfpj_GqdQzYX-Uu1AAcBQGXq7qY1cGnsREQ3U,8139
+code_context/adapters/driven/chunker_treesitter_queries.py,sha256=EHsvL5Mvf92WW50mVdZSuhQ9cpEYPGYjUXCXZN02i5c,3271
+code_context/adapters/driven/code_source_fs.py,sha256=HNpbNCEomtZxwfCTB7N1yVGQAiUfwTLIp1unevWHQx4,4159
+code_context/adapters/driven/embeddings_local.py,sha256=u_llGdxvg13hEfjU_8Y6iMI98lWl5zOguFcAA1_5sUE,4274
+code_context/adapters/driven/embeddings_openai.py,sha256=SIWmkI8HLiHtYM7V9WgnTrrAiAq8AV1qHgKlmmGmhcA,1572
+code_context/adapters/driven/git_source_cli.py,sha256=mIlNGh6v1Gh0a3424kCDc3ifemPsX70IK96ADKcApt4,7340
+code_context/adapters/driven/introspector_fs.py,sha256=1zicMEUduwZK6hjztdzq3UgkLyHKx0ECd85cMjg-zs8,7654
+code_context/adapters/driven/keyword_index_sqlite.py,sha256=qMxZ1tkOS2rtsZXW0F_MIm2GIRis3AQNHUOyLa03CnI,8351
+code_context/adapters/driven/reranker_crossencoder.py,sha256=fYEK4f6mMViUcM3i8gpanw1StbI6-3sTEOIry1yROrY,1837
+code_context/adapters/driven/symbol_index_sqlite.py,sha256=0Olb3CRe64kQt9b8QaCMXsZHeZcYtj4I04fZTeBHPrg,10934
+code_context/adapters/driven/vector_store_numpy.py,sha256=ZwLb50IaGa1byiuzSoOXFcSKpq72koaBjV1cXNkFEJY,4563
+code_context/adapters/driving/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_context/adapters/driving/mcp_server.py,sha256=Qj_fQhIHnduS1jFrO0I2V2r4OUHhYsfEWXOjTT8szZ0,14665
+code_context/domain/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_context/domain/index_bus.py,sha256=HOml7yz8IMKfnM8gCR9zaoEhI0ddheSUMzlQ8f08XzM,1829
+code_context/domain/models.py,sha256=OiDDgw3RzRtIKjcteIR9X8rkqKsY4bh0iXdrzBBXQyw,4048
+code_context/domain/ports.py,sha256=U8TjBJ_PaQ4d8NFk0l9oiCYK_LygdbdlwXj7AfVxRQs,6468
+code_context/domain/use_cases/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+code_context/domain/use_cases/explain_diff.py,sha256=Jws_LUq2bgXhPPFVx_kN-zlF0-ykPPSlnVdP-6NsN6E,4156
+code_context/domain/use_cases/find_definition.py,sha256=B3PmWYivSMscXaa0xujOq9pObYHX-TQ-OPgZ9TZgnsc,892
+code_context/domain/use_cases/find_references.py,sha256=tguFc39BYupV6PBlv14IIk6DgqVzm5UYAoLnSpNNLJg,641
+code_context/domain/use_cases/get_file_tree.py,sha256=qAjxnvrmnvaq5wRZoRkcXPxnJTlXxgVJk4uw5liRBFk,932
+code_context/domain/use_cases/get_summary.py,sha256=W5DPolHZbcPNsmv-TC13MVD6-dEi7L4_z4QYETuxsHg,901
+code_context/domain/use_cases/indexer.py,sha256=wUw2YHRjEyq7gN369kozle7lbpUhz_gLrPeHtDylMR8,14177
+code_context/domain/use_cases/recent_changes.py,sha256=Lg9SPIgO73D_4tWoIfdcLPp6KZXgQTsUkH7U0EBF9UA,1047
+code_context/domain/use_cases/search_repo.py,sha256=hAhaumSRh3LZI3qSZaGVK8x6khtleH2dI5MSVsoRRaA,5249
+code_context_mcp-1.0.0.dist-info/licenses/LICENSE,sha256=wTfupSQSWMPKgTgleNJcx0tXs0GZ8WU6Isu5h0y_f4E,1082
+code_context_mcp-1.0.0.dist-info/METADATA,sha256=DOEZFD4rae_CXS1Q92UeSuNDx5V8FdaX425pLZa3Q08,10792
+code_context_mcp-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+code_context_mcp-1.0.0.dist-info/entry_points.txt,sha256=Vl7r5xH8wUB-mfd_rVmwJQCrYAd9c3t-wo3dBn5dTCQ,102
+code_context_mcp-1.0.0.dist-info/top_level.txt,sha256=S4-Fe3nUrB2OIzEUjkjAfeJqc1gOsPaSakUM1sRUnHI,13
+code_context_mcp-1.0.0.dist-info/RECORD,,

code_context_mcp-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

code_context_mcp-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+code-context = code_context.cli:main
+code-context-server = code_context.server:main

code_context_mcp-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 code-context 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.

code_context_mcp-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+code_context