|
| 1 | +# MCP Tools Reference |
| 2 | + |
| 3 | +**Files**: `src/api/index.ts`, `src/api/tools/` |
| 4 | + |
| 5 | +58 MCP tools exposed via stdio and HTTP transports. |
| 6 | + |
| 7 | +## Tool groups |
| 8 | + |
| 9 | +| Group | Count | Condition | File | |
| 10 | +|-------|-------|-----------|------| |
| 11 | +| Context | 1 | always | `tools/context/` | |
| 12 | +| Docs | 5 | docs graph enabled | `tools/docs/` | |
| 13 | +| Code blocks | 4 | docs graph enabled | `tools/docs/` | |
| 14 | +| Cross-graph | 1 | docs + code enabled | `tools/docs/` | |
| 15 | +| Code | 5 | code graph enabled | `tools/code/` | |
| 16 | +| File index | 3 | always | `tools/file-index/` | |
| 17 | +| Knowledge | 12 | always | `tools/knowledge/` | |
| 18 | +| Tasks | 13 | always | `tools/tasks/` | |
| 19 | +| Skills | 14 | always | `tools/skills/` | |
| 20 | + |
| 21 | +## Context tool |
| 22 | + |
| 23 | +| Tool | Input | Output | |
| 24 | +|------|-------|--------| |
| 25 | +| `get_context` | — | `{ projectId, workspaceId?, workspaceProjects?, availableGraphs }` | |
| 26 | + |
| 27 | +## Docs tools |
| 28 | + |
| 29 | +| Tool | Input | Output | |
| 30 | +|------|-------|--------| |
| 31 | +| `list_topics` | — | `[{ fileId, title, chunks }]` | |
| 32 | +| `get_toc` | `fileId` | `[{ id, title, level }]` | |
| 33 | +| `search` | `query` + optional `topK`, `bfsDepth`, `maxResults`, `minScore`, `bfsDecay`, `searchMode` | `[{ id, fileId, title, content, level, score }]` | |
| 34 | +| `get_node` | `nodeId` | `{ id, fileId, title, content, level, mtime }` | |
| 35 | +| `search_topic_files` | `query` + optional `topK`, `minScore` | `[{ fileId, title, score }]` | |
| 36 | + |
| 37 | +## Code block tools |
| 38 | + |
| 39 | +| Tool | Input | Output | |
| 40 | +|------|-------|--------| |
| 41 | +| `find_examples` | `symbol` + optional `language`, `fileId` | `[{ id, fileId, language, symbols, content, parentId, parentTitle }]` | |
| 42 | +| `search_snippets` | `query` + optional `topK`, `minScore` | `[{ id, fileId, language, symbols, content, score }]` | |
| 43 | +| `list_snippets` | optional `fileId`, `language`, `filter` | `[{ id, fileId, language, symbols, preview }]` | |
| 44 | +| `explain_symbol` | `symbol` + optional `fileId` | `{ codeBlock, explanation, fileId }` | |
| 45 | + |
| 46 | +## Cross-graph tools |
| 47 | + |
| 48 | +| Tool | Input | Output | |
| 49 | +|------|-------|--------| |
| 50 | +| `cross_references` | `symbol` | `{ definitions, documentation, examples }` | |
| 51 | + |
| 52 | +Requires both DocGraph and CodeGraph to be enabled. Bridges code definitions with documentation examples. |
| 53 | + |
| 54 | +## Code tools |
| 55 | + |
| 56 | +| Tool | Input | Output | |
| 57 | +|------|-------|--------| |
| 58 | +| `list_files` | — | `[{ fileId, symbolCount }]` | |
| 59 | +| `get_file_symbols` | `fileId` | `[{ id, kind, name, signature, startLine, endLine, isExported }]` | |
| 60 | +| `search_code` | `query` + optional search params | `[{ id, fileId, kind, name, signature, docComment, startLine, endLine, score }]` | |
| 61 | +| `get_symbol` | `nodeId` | `{ id, fileId, kind, name, signature, docComment, body, startLine, endLine, isExported }` | |
| 62 | +| `search_files` | `query` + optional `topK`, `minScore` | `[{ fileId, score }]` | |
| 63 | + |
| 64 | +## File index tools |
| 65 | + |
| 66 | +| Tool | Input | Output | |
| 67 | +|------|-------|--------| |
| 68 | +| `list_all_files` | optional `directory`, `extension`, `language`, `filter`, `limit` | `[{ filePath, kind, fileName, extension, language, mimeType, size, fileCount }]` | |
| 69 | +| `search_all_files` | `query` + optional `topK`, `minScore` | `[{ filePath, fileName, extension, language, size, score }]` | |
| 70 | +| `get_file_info` | `filePath` | `{ filePath, kind, fileName, directory, extension, language, mimeType, size, fileCount, mtime }` | |
| 71 | + |
| 72 | +## Knowledge tools |
| 73 | + |
| 74 | +| Tool | Input | Output | |
| 75 | +|------|-------|--------| |
| 76 | +| `create_note` | `title`, `content`, optional `tags` | `{ noteId }` | |
| 77 | +| `update_note` | `noteId` + optional `title`, `content`, `tags` | `{ noteId, updated }` | |
| 78 | +| `delete_note` | `noteId` | `{ noteId, deleted }` | |
| 79 | +| `get_note` | `noteId` | `{ id, title, content, tags, createdAt, updatedAt }` | |
| 80 | +| `list_notes` | optional `filter`, `tag`, `limit` | `[{ id, title, tags, updatedAt }]` | |
| 81 | +| `search_notes` | `query` + optional search params | `[{ id, title, content, tags, score }]` | |
| 82 | +| `create_relation` | `fromId`, `toId`, `kind` + optional `targetGraph` | `{ fromId, toId, kind, targetGraph?, created }` | |
| 83 | +| `delete_relation` | `fromId`, `toId` + optional `targetGraph` | `{ fromId, toId, deleted }` | |
| 84 | +| `list_relations` | `noteId` | `[{ fromId, toId, kind, targetGraph? }]` | |
| 85 | +| `find_linked_notes` | `targetId`, `targetGraph` | `[{ noteId, kind }]` | |
| 86 | +| `add_note_attachment` | `noteId`, `filename`, `content` (base64) | `{ noteId, filename, added }` | |
| 87 | +| `remove_note_attachment` | `noteId`, `filename` | `{ noteId, filename, removed }` | |
| 88 | + |
| 89 | +## Task tools |
| 90 | + |
| 91 | +| Tool | Input | Output | |
| 92 | +|------|-------|--------| |
| 93 | +| `create_task` | `title` + optional `description`, `status`, `priority`, `tags`, `dueDate`, `estimate`, `assignee` | `{ taskId }` | |
| 94 | +| `update_task` | `taskId` + optional fields | `{ taskId, updated }` | |
| 95 | +| `delete_task` | `taskId` | `{ taskId, deleted }` | |
| 96 | +| `get_task` | `taskId` | `{ id, title, description, status, priority, tags, dueDate, estimate, assignee, completedAt, createdAt, updatedAt, subtasks, blockedBy, blocks, related }` | |
| 97 | +| `list_tasks` | optional `status`, `priority`, `tag`, `filter`, `assignee`, `limit` | `[{ id, title, status, priority, tags, dueDate, estimate, assignee, completedAt }]` | |
| 98 | +| `search_tasks` | `query` + optional search params | `[{ id, title, description, status, priority, tags, score }]` | |
| 99 | +| `move_task` | `taskId`, `status` | `{ taskId, status, completedAt }` | |
| 100 | +| `link_task` | `fromId`, `toId`, `kind` (`subtask_of`, `blocks`, `related_to`) | `{ fromId, toId, kind, created }` | |
| 101 | +| `create_task_link` | `taskId`, `targetId`, `targetGraph` | `{ taskId, targetId, targetGraph, created }` | |
| 102 | +| `delete_task_link` | `taskId`, `targetId`, `targetGraph` | `{ taskId, targetId, deleted }` | |
| 103 | +| `find_linked_tasks` | `targetId`, `targetGraph` | `[{ taskId, kind }]` | |
| 104 | +| `add_task_attachment` | `taskId`, `filename`, `content` (base64) | `{ taskId, filename, added }` | |
| 105 | +| `remove_task_attachment` | `taskId`, `filename` | `{ taskId, filename, removed }` | |
| 106 | + |
| 107 | +## Skill tools |
| 108 | + |
| 109 | +| Tool | Input | Output | |
| 110 | +|------|-------|--------| |
| 111 | +| `create_skill` | `title` + optional `description`, `steps`, `triggers`, `source`, `tags` | `{ skillId }` | |
| 112 | +| `update_skill` | `skillId` + optional fields | `{ skillId, updated }` | |
| 113 | +| `delete_skill` | `skillId` | `{ skillId, deleted }` | |
| 114 | +| `get_skill` | `skillId` | `{ id, title, description, steps, triggers, source, tags, usageCount, lastUsedAt, createdAt, updatedAt, dependsOn, dependedBy, related, variants }` | |
| 115 | +| `list_skills` | optional `source`, `tag`, `filter`, `limit` | `[{ id, title, source, tags, usageCount, lastUsedAt }]` | |
| 116 | +| `search_skills` | `query` + optional search params | `[{ id, title, description, source, tags, score }]` | |
| 117 | +| `recall_skills` | `query` + optional `topK`, `maxResults` | `[{ id, title, description, steps, triggers, source, tags, score }]` | |
| 118 | +| `bump_skill_usage` | `skillId` | `{ skillId, usageCount, lastUsedAt }` | |
| 119 | +| `link_skill` | `fromId`, `toId`, `kind` (`depends_on`, `related_to`, `variant_of`) | `{ fromId, toId, kind, created }` | |
| 120 | +| `create_skill_link` | `skillId`, `targetId`, `targetGraph` | `{ skillId, targetId, targetGraph, created }` | |
| 121 | +| `delete_skill_link` | `skillId`, `targetId`, `targetGraph` | `{ skillId, targetId, deleted }` | |
| 122 | +| `find_linked_skills` | `targetId`, `targetGraph` | `[{ skillId, kind }]` | |
| 123 | +| `add_skill_attachment` | `skillId`, `filename`, `content` (base64) | `{ skillId, filename, added }` | |
| 124 | +| `remove_skill_attachment` | `skillId`, `filename` | `{ skillId, filename, removed }` | |
| 125 | + |
| 126 | +## Mutation serialization |
| 127 | + |
| 128 | +Mutation tools (create/update/delete) are wrapped via `createMutationServer()` — a proxy that enqueues every mutation handler into a `PromiseQueue`. This prevents race conditions from parallel MCP sessions. |
| 129 | + |
| 130 | +Read-only tools (list, get, search) run freely without queueing. |
| 131 | + |
| 132 | +## Transports |
| 133 | + |
| 134 | +| Transport | Method | Use case | |
| 135 | +|-----------|--------|----------| |
| 136 | +| **stdio** | `startStdioServer()` | IDE integration, single project | |
| 137 | +| **HTTP** | `startMultiProjectHttpServer()` | Multi-project, remote clients | |
| 138 | + |
| 139 | +### HTTP session management |
| 140 | + |
| 141 | +- Route: `/mcp/{projectId}` |
| 142 | +- Each POST creates a new session (`randomUUID()`), returned via `mcp-session-id` header |
| 143 | +- Sessions share graph instances via `ProjectManager` |
| 144 | +- Idle session sweep every 60s (configurable timeout, default 30 min) |
0 commit comments