Metadata-Version: 2.4
Name: promptify-cmax
Version: 0.1.0
Summary: Call-graph-aware code context retrieval for AI coding agents (MCP server + CLI)
Project-URL: Homepage, https://promptify.com
Project-URL: Repository, https://github.com/promptify-com/promptify-cmax
Project-URL: Issues, https://github.com/promptify-com/promptify-cmax/issues
Author-email: Promptify LLC <support@promptify.com>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: ai-agents,claude-code,code-context,mcp,structural-retrieval
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Requires-Python: >=3.12
Requires-Dist: mcp>=1.0
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Requires-Dist: watchdog>=4.0
Description-Content-Type: text/markdown

# promptify-cmax

**Call-graph-aware code context retrieval for AI coding agents.**

When you ask Claude Code, Cursor, or any agent to fix a function, the agent typically searches the codebase with `grep` and pulls back every file that *mentions* the symbol — including specs, plans, ADRs, and unrelated definitions that happen to share a name. The model pays attention tax on all of it.

`promptify-cmax` returns the files most likely to need editing, ranked by **distance in the call graph** rather than surface name match. It exposes both an [MCP](https://modelcontextprotocol.io/) server (drop-in for Claude Code, Cursor, etc.) and a CLI.

## Why

On a SWE-bench-derived smoke test (n=20), grep-based retrieval returned a median **142× more tokens** than the agent actually needed; structural retrieval returned the same target files at **49× lower token cost**. A reproducible benchmark at full scale (n≥200, SWE-bench-Verified) is in `bench/` — published numbers will live there.

## Status

**Beta** — Python and TypeScript indexing, FQN-aware call resolution, MCP server. License: Apache-2.0.

## Install

```bash
pip install promptify-cmax
```

Then index your project and wire it into Claude Code / Cursor / Continue. Five-minute walkthrough with copy-pasteable MCP config snippets and troubleshooting: **[QUICKSTART.md](./QUICKSTART.md)**.

## What it exposes

CLI:
- `promptify-cmax index --project-root <dir>` — build / incrementally update the structural index (one-time per repo, then automatic-on-change)
- `promptify-cmax query --project-root <dir> "<task>"` — return ranked files for a task description
- `promptify-cmax serve --project-root <dir>` — run as an MCP server over stdio

MCP tools (when run as `serve`):
- `structural_context(task, top_k=5)` — rank files by call-graph distance from the task's identifiers
- `reindex()` — rebuild after large code changes

## How it works

1. **Index** (one-time per repo, then incremental on file change): tree-sitter walks every Python and TypeScript source file, extracts function definitions, intra-function call sites, and module-level imports; persists everything to a single SQLite file at `.promptify/code-index.db`.
2. **Resolve** (query time): given a natural-language task, extract candidate identifiers (backtick / CamelCase / snake_case / dotted paths) and intersect with the symbols actually in the index.
3. **BFS** (query time): walk the call graph two hops in both directions; resolve each call edge to a *specific* `(file, function)` tuple via the caller's import bindings and same-file scope, so two functions named `helper` in different files never collapse into one node.
4. **Rank**: group reached nodes by file, sort by `(distance ASC, affected-function-count DESC)`, return the top-k.

The discipline that makes this useful: **fully-qualified-name resolution**, not bare-name matching. A naive call graph treats every `def main(): ...` in the repo as the same node — typically 100+ collisions in any non-trivial Python project. We resolve through imports, so cross-file false positives don't enter the BFS frontier.

## Roadmap

- [x] Python + TypeScript indexing (v0.1)
- [x] FQN-aware call resolution
- [x] MCP server, CLI
- [ ] Go, Rust, Java, C# (Pro)
- [ ] Hosted multi-repo index (Pro)
- [ ] PR-bot / CI integration (Team)
- [ ] VSCode + JetBrains extensions

## Pro / Team

This package is the open-source core. [Promptify](https://promptify.com) sells a hosted layer for teams: multi-repo indexing that survives laptop churn, additional language support, token-savings analytics, editor extensions, SSO/SAML, and CI integration. Pricing and signup at [promptify.com/context](https://promptify.com/context).

## Contributing

See [CONTRIBUTING.md](./CONTRIBUTING.md). Issues and PRs welcome.

## License

Apache-2.0. Copyright © 2026 Promptify LLC. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).
