API ВЕГАcodetopo
Идентификатор в реестре: mcp-name: io.github.nrupala/codetopo
Смотрите на свою кодовую базу глазами агента. codetopo преобразует исходный репозиторий в граф кода, по которому можно выполнять запросы: символы, вызовы, ссылки и структура. Результаты возвращаются в формате JSON, с которым AI-агент для работы с кодом может действовать напрямую.
codetopo получил знак OpenSSF Best Practices Passing — выполнено 100% из 67 критериев.
Вы здесь, потому что агент только что работал с вашей кодовой базой, и вам нужно быстро разобраться в её структуре: что вызывает эту функцию? Что сломается, если я её изменю? Как связаны эти два модуля? codetopo один раз индексирует дерево и отвечает на такие вопросы в виде данных — сначала показывает количество, а полные списки выводит только по запросу. Доступны CLI, HTTP API и инструменты MCP, с которыми уже работает ваш агент.
codetopo намеренно не зависит от предметной области: он не выставляет оценки, не ранжирует результаты и не высказывает мнений о значении кода. Он отвечает только на вопросы о структуре исходного дерева. Интерпретация предметного смысла остаётся агентам и командам, которые строят решения на основе codetopo.
codetopo — продукт компании AIMLDS (2351485 ALBERTA INC.), создавшей Conduit — управляемую инфраструктуру для подключения MCP, где каждый вызов маршрутизируется, учитывается и сопровождается квитанцией.
Демонстрация: codetopo.aimlds.org — настоящая карта этого репозитория, построенная самим codetopo и обновляемая при каждом push в main.
Быстрый старт за 60 секунд
Требуется стабильная toolchain Rust (установите её с помощью rustup).
# Install the four binaries: codetopo (CLI), codetopo-server (HTTP API),
# codetopo-mcp (stdio MCP server), codetopo-acp (stdio ACP agent).
# The packages must be named — a bare install URL fails because the
# repository contains multiple binary packages.
cargo install --git https://github.com/nrupala/codetopo codetopo-cli codetopo-server codetopo-mcp codetopo-acp
# Index a repository (Rust and TypeScript/JavaScript are parsed via tree-sitter)
codetopo index ~/my-project --db graph.db
# Find a symbol's id by name (every surface has this discovery step)
codetopo search connect --db graph.db
# Ask what calls what (the package prefix is your directory's name,
# exactly as indexed — hyphen included)
codetopo descendants my-project::net::Client::connect --db graph.db --expand
На этом весь процесс: однажды индексируйте, затем запрашивайте данные. По умолчанию результаты сначала показывают агрегированные данные — итоги перед списками. Это помогает экономно расходовать токены и не перегружать конвейеры; параметр --expand выводит полный список, когда он нужен.
Примеры запросов
Запросы выполняются к тестовому репозиторию, который используется для сквозной проверки проекта (docs/phase-2-verification.md). Ниже приведён фактический результат работы CLI:
$ codetopo index crates/codetopo-server/tests/fixture-repo --db graph.db
files indexed: 3
files failed: 0
symbols: 6
nodes: 15
edges: 23
diagnostics: 2
$ codetopo stats --db graph.db
nodes: 15
package: 1
module: 3
file: 3
function: 6
external: 2
edges: 23
calls: 5
contains: 12
reads: 6
$ codetopo descendants fixture-repo::alpha::entry --db graph.db --expand
2 descendants of fixture-repo::alpha::entry
fixture-repo::alpha::helper_a
fixture-repo::alpha::helper_b
Вот ещё несколько вопросов, на которые можно получить ответ с помощью того же движка и тех же данных:
--db graph.db # what depends on this node codetopo blast-radius --db graph.db # what a failure here would take with it codetopo path --db graph.db # shortest typed path between two nodes codetopo verify --db graph.db # verify the hash-chained audit log codetopo snapshot --db graph.db --out g.json # portable frozen JSON export of the whole graph codetopo restore --snapshot g.json --db g2.db # restore a snapshot into a fresh database">
codetopo ancestors <node-id> --db graph.db # what depends on this node
codetopo blast-radius <node-id> --db graph.db # what a failure here would take with it
codetopo path <from-id> <to-id> --db graph.db # shortest typed path between two nodes
codetopo verify --db graph.db # verify the hash-chained audit log
codetopo snapshot --db graph.db --out g.json # portable frozen JSON export of the whole graph
codetopo restore --snapshot g.json --db g2.db # restore a snapshot into a fresh database
Результат запроса path отображается как последовательность типизированных шагов, например: a --calls--> x --imports--> b
(для примера; точные идентификаторы зависят от индекса).
Подключение к агенту
HTTP API (codetopo-server)
Те же запросы доступны через JSON, защищены авторизацией по Bearer API-key и учитываются для каждого запроса. Это единый способ взаимодействия для любых клиентов и языков:
api_keys && chmod 600 api_keys codetopo-server # listens on 127.0.0.1:8080 by default
curl -H "Authorization: Bearer $KEY" -X POST localhost:8080/v1/index
-H 'Content-Type: application/json' -d '{"repo_path": "~/my-project"}'
{"index_id": "", "files_indexed": 3, "files_failed": 0, "nodes": 15, "edges": 23, "diagnostics": 2}
curl -H "Authorization: Bearer $KEY"
"localhost:8080/v1/graphs//descendants?node=&expand=true"">
KEY="demo-key:$(openssl rand -hex 16)" # a fresh random secret, generated exactly as docker-compose does — never a published example value
echo "$KEY" > api_keys && chmod 600 api_keys
codetopo-server # listens on 127.0.0.1:8080 by default
curl -H "Authorization: Bearer $KEY" -X POST localhost:8080/v1/index \
-H 'Content-Type: application/json' -d '{"repo_path": "~/my-project"}'
# {"index_id": "<uuid>", "files_indexed": 3, "files_failed": 0, "nodes": 15, "edges": 23, "diagnostics": 2}
curl -H "Authorization: Bearer $KEY" \
"localhost:8080/v1/graphs/<uuid>/descendants?node=<node-id>&expand=true"
Двенадцать конечных точек в /v1: одна операция индексации и одиннадцать запросов только для чтения: POST /v1/index, GET /v1/graphs/{id}/{descendants, ancestors, blast-radius, path, stats, verify, snapshot, neighborhood, symbol, search}, GET /v1/schema. Полное описание API приведено в schemas/openapi.yaml (OpenAPI 3.1.0). Параметры окружения (CODETOPO_BIND, CODETOPO_DATA_DIR, CODETOPO_KEYS_FILE, CODETOPO_METERING_LOG) описаны в schemas/README.md.
MCP (codetopo-mcp)
JSON-RPC-сервер, работающий через stdio и предоставляющий тот же уровень обработчиков в виде двенадцати инструментов: восемь инструментов для запросов и проверки целостности (codetopo_index, codetopo_descendants, codetopo_ancestors, codetopo_blast_radius, codetopo_path, codetopo_stats, codetopo_verify, codetopo_snapshot), а также инструменты для поиска и изучения схемы (codetopo_search_symbols, codetopo_get_symbol, codetopo_neighborhood, codetopo_describe_schema). Благодаря этому встроенному агенту достаточно освоить один интерфейс, чтобы получить доступ ко всем возможностям. Ответы MCP полностью совпадают с ответами HTTP: оба интерфейса используют одни и те же запросы codetopo-core.
{ "mcpServers": { "codetopo": { "command": "codetopo-mcp" } } }
ACP (codetopo-acp)
Агент, работающий через stdio и поддерживающий Agent Client Protocol. Он предназначен для редакторов и клиентов, которые взаимодействуют с агентами, а не вызывают инструменты напрямую. Откройте сессию в рабочем каталоге и задавайте вопросы о структуре кода обычным языком:
","prompt":"blast radius of auth::login"}} ← {"jsonrpc":"2.0","id":3,"result":{"answer":"Blast radius of 'auth::login': 14 nodes — …"}}">
→ {"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}
← {"jsonrpc":"2.0","id":1,"result":{"agent":"codetopo","protocolVersion":"1.0",
"agentCapabilities":{"read_only":true,"code_structure":true},"agentInfo":{"name":"codetopo"}}}
→ {"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/path/to/repo"}}
→ {"jsonrpc":"2.0","id":3,"method":"session/prompt",
"params":{"sessionId":"<id>","prompt":"blast radius of auth::login"}}
← {"jsonrpc":"2.0","id":3,"result":{"answer":"Blast radius of 'auth::login': 14 nodes — …"}}
Маршрутизация запросов по типу намерения (descendants / ancestors / blast-radius / path / stats / snapshot / verify) детерминированно направляет их к тем же запросам codetopo-core — без LLM, сети и записи файлов. На запросы об изменении кода агент честно отвечает отказом, поскольку работает только на чтение. В stdout передаются только протокольные сообщения; диагностические данные выводятся в stderr.
Размещённый API (codetopo Hosted)
Мы постоянно поддерживаем тот же HTTP API. Индекс размещён у нас: отправьте репозиторий (публичный git URL или архив) и запрашивайте граф откуда угодно с помощью своего ключа. Локальная установка и собственный сервер не нужны.
19 долларов США в месяц за ключ.
| Включено | |
|---|---|
| Активные индексы | 25 |
| Запросы | 10,000 / месяц |
| Размер репозитория | до 50,000 файлов на индекс |
Как это работает:
-
Оформите подписку — оплату обрабатывает Stripe.
-
После оплаты вы перейдёте на страницу получения ключа API. Заберите ключ там — он показывается только один раз, поэтому сохраните его сразу.
-
Отправляйте запросы к API по адресу
https://codetopo-api.aimlds.org, указав
Authorization: Bearer :. Контракт такой же, как у самостоятельно размещённого сервера (см. schemas/).
Отменить подписку можно в любое время по ссылке в квитанции Stripe. Ключ останется активным до конца оплаченного периода, после чего будет отозван.
Это размещённая версия того же продукта. Локальные CLI, MCP-сервер и ACP-агент в этом репозитории остаются бесплатными и имеют открытый исходный код (AGPL-3.0); они не изменились. Размещённый тариф подойдёт, если вы хотите пользоваться графом через сервер, а не устанавливать его у себя.
Архитектура
┌─────────────┐ tree-sitter ┌──────────────┐
│ source tree │ ───────────────► │ codetopo- │ extract symbols,
└─────────────┘ Rust, TS/JS │ extract │ calls, references
└──────┬───────┘
▼
┌──────────────┐
│ codetopo-core│ graph model:
│ │ nodes, edges,
│ │ traversal queries
└──────┬───────┘
▼
┌──────────────┐
│ codetopo- │ SQLite store +
│ store │ hash-chained
│ │ audit log
└──────┬───────┘
│
┌──────────────────────────────────┼─────────────────────────────┐
▼ ▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ codetopo │ │ codetopo- │ Bearer auth │ codetopo- │ stdio │ codetopo- │ stdio
│ (CLI) │ │ server │ JSONL │ mcp │ JSON-RPC │ acp │ ACP
└──────────────┘ └──────────────┘ metering └──────────────┘ └──────────────┘
| Crate | Назначение |
|---|---|
codetopo-core | Модель графа, типы узлов и рёбер, все запросы для обхода графа, снимки |
codetopo-extract | Экстракторы на основе tree-sitter (Rust, TypeScript/JavaScript) |
codetopo-store | Хранение данных в SQLite и защищённый от подделки журнал аудита с цепочкой хешей |
codetopo-cli | CLI codetopo для работы без графического интерфейса — эталонный интерфейс запросов |
codetopo-server | HTTP API codetopo-server на axum — тонкий адаптер поверх core |
codetopo-mcp | MCP-сервер codetopo-mcp с обменом данными через stdio — тонкий адаптер поверх core |
codetopo-acp | ACP-агент codetopo-acp с обменом данными через stdio — диалоговые сессии по протоколу Agent Client Protocol; тонкий адаптер поверх core |
Интерфейсы CLI, HTTP, MCP и ACP — это тонкие адаптеры над одними и теми же обработчиками, поэтому их поведение не может различаться. В schemas/ хранятся машиночитаемые контракты (OpenAPI 3.1 и каталог инструментов MCP), которые сверяются с работающими серверами. Журнал аудита хранилища следует принципу доверенного примитива, используемому во всей линейке продуктов: это неизменяемая запись только для добавления, связанная цепочкой хешей и проверяемая с помощью codetopo verify / GET …/verify.
Документация
-
Журнал разработки — простым языком о том, как появился codetopo и куда он движется. Журнал публикуется вместе с релизами; ссылка на него есть и на демонстрационном сайте.
-
docs/render.md — детерминированная визуализация: неизменяемая спецификация расположения элементов (JSON) и правила SVG, используемые в
codetopo render -
docs/protocol-proof.md — подтверждение соответствия MCP/ACP: строгие stdio-клиенты и проверка по официальным схемам
-
docs/scale-gate.md — проверка масштабирования на 10,000 файлов и результаты измерений
-
Dockerfile + docker-compose.yml — контейнер для самостоятельного размещения: HTTP API для работы с вашими индексами
-
docs/phase-2-design.md — проектирование API: конечные точки, авторизация, учёт использования и принцип aggregate-first
-
docs/phase-2-verification.md — отчёт о сквозной проверке; приведённые выше показатели для тестового набора взяты из этого документа
-
docs/phase-3-acp-design.md — проектирование ACP-агента: протокол обмена данными, маршрутизация намерений, гарантия доступа только для чтения
-
docs/phase-3-acp-verification.md — отчёт о проверке ACP
-
docs/quickstart-verification.md — проверка инструкции по быстрому запуску и приведённых выше примеров запросов на чистой машине
-
schemas/README.md — два контракта для агентов и отличия спецификации от документа с описанием проекта
-
CODE_SCHEMA.md — схема графа (§6 устанавливает правило aggregate-first)
Политика конфиденциальности
codetopo полностью работает на вашем компьютере. MCP-сервер (codetopo-mcp), CLI и создаваемые ими базы данных индексов никогда не отправляют ваш код, запросы или данные об использовании куда-либо: здесь нет учётных записей, ключей API, телеметрии и сетевых обращений во время работы. При индексировании читаются только указанные вами репозитории, а запись выполняется только в заданные вами пути к базам данных. Чтобы удалить свои данные, удалите файлы баз данных индексов (файлы .db или каталог данных HTTP-сервера): на сервере ничего не хранится, поэтому удалять данные где-либо ещё не потребуется. Чтобы перенести данные, экспортируйте их командой snapshot: она сохранит весь граф в одном переносимом файле JSON. Вопросы о конфиденциальности: info@aimlds.org.
Лицензия
-
Ядро (
codetopo-*crates): AGPL-3.0-or-later (см.LICENSES/) -
Контракты для взаимодействия с агентами (
schemas/: спецификация OpenAPI 3.1 и каталог инструментов MCP): Apache-2.0 (см.schemas/LICENSE-APACHE)
Принадлежит Nrupal Akolkar · Создано с помощью Muse by Meta. Присоединитесь к Muse, затем в течение 48 часов после регистрации активируйте код 101EEK в разделе Settings — и мы оба получим токены.