CodeGraphPlus

CodeGraphPlus

Build a local API and data-asset knowledge graph for any target project, exposed to OpenCode, Cursor, and other AI tools via MCP — without repeatedly grepping or reading spec and config files in chat.

Architecture follows CodeGraph: transport → session → engine → tools, stdio JSON-RPC MCP. Design rationale and architecture: docs/CONCEPT.md.

---

What it does

After codegraphplus init -i in a project root, CodeGraphPlus creates .codegraphplus/ and writes these assets and their relations to a local SQLite graph:

Asset kind	Meaning	Example
http_api	HTTP / RPC routes	GET /users/{id}
http_dependency	Outbound HTTP to other services	call payment-service /charge
db_table	Database tables	orders, user_profile
redis_key	Redis key patterns	session:{userId}
topic	Message topics	order.created
dto_schema	Request / response schemas	CreateOrderRequest
thread_pool	Thread pools / executors	asyncExecutor

Relation types (filled when indexers are implemented): uses_table, uses_redis, publishes, subscribes, uses_schema, calls_http, runs_on_pool, references.

Typical use: open a Java backend project in OpenCode and query API routes, related tables, Redis keys, topics, and dependencies via MCP.

Scope: Indexers and docs target Java backend projects (Spring Boot, Maven/Gradle, Flyway, JPA, Feign, etc.). TypeScript / Node / Python / Go targets are not supported by built-in indexers yet.

Current status: Indexer plugin interfaces are ready; parsing is stub — candidate files are scanned and tracked, but assets are not written yet. indexStatus is stub; the graph may be empty; MCP tools still work and return empty results (not errors).

---

Requirements

• Node.js >= 22.5 (uses built-in node:sqlite)

---

Installation

1. Clone and build

git clone <repo-url> CodeGraphPlus
cd CodeGraphPlus
npm install
npm run build

Output is in dist/; CLI entry: dist/bin/codegraphplus.js.

2. Use the CLI (pick one)

Option A — npm global (recommended for end users)

npm install -g codegraphplus
codegraphplus install
codegraphplus --version

Option B — local development (npm link)

npm link
codegraphplus install --dev
codegraphplus --version

Option C — invoke via node

node dist/bin/codegraphplus.js --help
node dist/bin/codegraphplus.js install --dev

Option D — npm script

npm run cli -- --help
npm run cli -- init -i --path C:/path/to/target-project

3. Verify

npm test
codegraphplus --version

4. Enable in a target project

Run in the business project that needs a graph (not inside the CodeGraphPlus repo):

cd /path/to/your-service
codegraphplus init -i
codegraphplus status

---

Source layout

Application code lives under src/:

CodeGraphPlus/
├── src/
│   ├── bin/                 ★ CLI entry (codegraphplus command)
│   ├── mcp/                 ★ MCP server (OpenCode / Cursor)
│   ├── indexer/             ★ Indexer plugins (API, tables, Redis, topics, …)
│   ├── enrich/              ★ Agent write-back (baseline + apply updates)
│   ├── db/                  ★ SQLite layer
│   ├── index.ts             ★ Core facade (init / index / search)
│   ├── directory.ts           .codegraphplus/ directory helpers
│   └── types.ts               Asset and relation types
├── docs/
│   ├── CONCEPT.md             Design (why, vs CodeGraph, architecture)
│   ├── EXTENDING.md           Extension guide (indexers, plugins)
│   └── CONSISTENCY.md         Graph version / multi-agent alignment
├── __tests__/                 Tests
├── dist/                      Build output (npm run build)
├── package.json
└── tsconfig.json

Path	Role	When to edit
src/bin/	CLI: init, index, status, search, serve --mcp	New commands, CLI flags
src/mcp/	MCP: transport → session → engine → tools	MCP tools, server instructions
src/indexer/	Indexer orchestration + built-in plugins	Real indexing (tables, APIs, Redis, …)
src/enrich/	Baseline report + applyUpdates	Agent graph updates
src/db/	schema.sql, queries.ts, SQLite adapter	Schema and queries
src/index.ts	CodeGraphPlus class	Public API
src/directory.ts	.codegraphplus/ creation and discovery	Index directory rules
src/types.ts	AssetKind, RelationKind	New asset/relation kinds

Data is not in this repo: the index DB is written to .codegraphplus/codegraphplus.db in each target project.

Suggested reading order:

1. src/bin/codegraphplus.ts — CLI entry
2. src/index.ts + src/indexer/index.ts — init / index flow
3. src/mcp/tools.ts — MCP surface
4. src/indexer/plugins/ — built-in stub plugins

---

Initialize a target project

cd /path/to/your-service
codegraphplus init -i

Creates:

your-service/
  .codegraphplus/
    codegraphplus.db
    .gitignore

CLI commands

Command	Description
codegraphplus init [path]	Create .codegraphplus/ only
codegraphplus init -i [path]	Create + run stub index
codegraphplus index [path]	Re-run index
codegraphplus plugins [path]	List indexer slots and scripts
codegraphplus baseline [path]	Baseline report (Agent enrichment)
codegraphplus traverse --kind <kind> [path]	Paginated traversal by kind
codegraphplus apply --file patches.json	Apply Agent patch JSON
codegraphplus status [path]	Kind counts and indexStatus
codegraphplus search <query> [path]	CLI search
codegraphplus install	Register MCP in Cursor / OpenCode
codegraphplus version [path]	Graph version
codegraphplus serve --mcp [--path <path>]	Start MCP server

Path examples:

node C:/ApiGraph/dist/bin/codegraphplus.js init -i --path C:/path/to/target-project
node C:/ApiGraph/dist/bin/codegraphplus.js status --path C:/path/to/target-project

---

MCP configuration

Automatic (recommended)

After installing the CLI globally:

codegraphplus install

This registers the MCP server in:

Target	Global config (default)
Cursor	~/.cursor/mcp.json
OpenCode	~/.config/opencode/opencode.jsonc

Options:

codegraphplus install --target cursor          # Cursor only
codegraphplus install --target opencode        # OpenCode only
codegraphplus install --location local         # project .cursor/mcp.json
codegraphplus install --dev                    # use node + script path (npm link / dev)
codegraphplus install --print                  # show config without writing
codegraphplus install --uninstall              # remove entries

Restart Cursor / OpenCode after install.

Manual

codegraphplus serve --mcp --path /path/to/target-project

Example for .cursor/mcp.json (when not using install):

{
  "mcpServers": {
    "codegraphplus": {
      "command": "codegraphplus",
      "args": ["serve", "--mcp", "--path", "${workspaceFolder}"]
    }
  }
}

Why --path? Cursor often starts MCP with a cwd that is not the workspace root and may not pass rootUri on initialize. Like CodeGraph, ${workspaceFolder} points at the project that contains .codegraphplus/.

For projects on another machine, pass projectPath on tool calls.

MCP behavior

Project state	initialize	tools/list	Tool calls
Not initialized	inactive instructions	empty list	unavailable
Initialized, stub index	full playbook	11 tools	OK; empty graph returns empty (not error)
Initialized, enriched / real index	same	11 tools	graph data

---

MCP tools

Tool	Purpose	CodeGraph analogue
codegraphplus_explore	Primary — explore an API/data area	codegraph_explore
codegraphplus_search	Cross-kind search	codegraph_search
codegraphplus_node	Single asset details	codegraph_node
codegraphplus_dependencies	What an asset uses	codegraph_callees
codegraphplus_consumers	Who uses an asset	codegraph_callers
codegraphplus_impact	Change impact	codegraph_impact
codegraphplus_files	Tracked spec/config files	codegraph_files
codegraphplus_status	Index health, kind stats	codegraph_status
codegraphplus_baseline	Indexer baseline overview	—
codegraphplus_traverse	Paginated traversal by kind	—
codegraphplus_apply_updates	Agent write-back	—

All tools accept optional projectPath for cross-project queries.

Agent enrichment

CodeGraphPlus does not run an LLM; the Agent reads code and writes back via MCP:

1. codegraphplus_traverse — kind (e.g. db_table, http_api), paginate with nextOffset
2. Read/Grep each sourceFile
3. codegraphplus_apply_updates (try dryRun: true first)
4. Verify with codegraphplus_search / codegraphplus_explore

CLI: codegraphplus traverse --kind db_table, codegraphplus apply --file patches.json [--dry-run]

See Extension guide — Agent enrichment.

---

Indexer plugins (extension)

Recommended: map each slot in .codegraphplus/indexers.config.json (e.g. db-table → plugins/db-table.ts); use null for the built-in stub. CLI: codegraphplus plugins.

Built-in plugins in src/indexer/plugins/ are currently stubs:

Plugin	Scans (Java)
openapi	OpenAPI / Swagger (yaml, json)
db-table	Flyway / Liquibase SQL, JPA @Entity, MyBatis XML
redis	application.yml, Redis config
topic	Spring Kafka / RabbitMQ
thread-pool	@EnableAsync, ThreadPoolTaskExecutor
http-dependency	OpenFeign, RestTemplate, WebClient

Details: Extension guide.

---

Development

npm run dev      # tsc --watch
npm test
npm run cli -- status /path/to/project
npm run clean    # remove dist/

---

vs CodeGraph

	CodeGraph	CodeGraphPlus
Index target	Code symbols, call graph	APIs, tables, Redis, topics, …
Index dir	.codegraph/	.codegraphplus/
Parsing	tree-sitter AST	Java multi-plugin (OpenAPI, Flyway, JPA, Feign, …)
Project languages	Multi-language	Java backend (current)
Daemon / file watch	Yes	No (direct stdio MCP)
MCP install helper	codegraph install	codegraphplus install

---

Publishing to npm

Maintainers (requires npm login):

npm run build
npm test
npm publish --access public

prepublishOnly runs build + tests automatically. The published package includes dist/, README.md, and LICENSE only.

---

MIT