@zokizuan/satori-mcp 1.0.2 → 3.0.0

package/README.md

@@ -1,130 +1,53 @@
 # @zokizuan/satori-mcp
 
-MCP server for Satori.
-Satori means "sudden insight"; this package turns core indexing/search into agent-safe MCP actions.
-
-Maintained by: `ham-zax` (`@zokizuan`).
-
-## Breaking Change (v1.0.0)
-
-Tool surface is now hard-broken to 4 tools only:
-
-- `manage_index`
-- `search_codebase`
-- `read_file`
-- `list_codebases`
-
-Removed tools from pre-1.0 releases are no longer routed.
+MCP server for Satori — agent-safe semantic code search and indexing.
 
 ## Features
 
-- Capability-driven execution via `CapabilityResolver`.
-- Unified `search_codebase` flow with optional reranker override:
-  - `useReranker=true`: force rerank (errors if capability missing)
-  - `useReranker=false`: disable rerank
-  - `useReranker` omitted: auto behavior by capability/profile
-- Snapshot `v3` safety with index fingerprints and strict `requires_reindex` access gates.
-- Deterministic train-in-the-error responses for incompatible or legacy index states.
-- Query-time exclusion support with `.gitignore`-style matching.
-- Structured search telemetry logs (`[TELEMETRY]` JSON to `stderr`).
-- Zod-first tool schemas converted to MCP JSON Schema for `ListTools`.
-- Auto-generated tool docs in this README from live tool schemas.
-- `read_file` line-range retrieval with default large-file truncation guard.
-- Optional proactive sync watcher mode (debounced filesystem events).
-- Index-time AST scope breadcrumbs (TS/JS/Python) rendered in search output as `🧬 Scope`.
-- Fingerprint schema bump to `dense_v2`/`hybrid_v2` with strict reindex gate for legacy `*_v1` indexes.
-- Non-AST files (for example Markdown) remain searchable when included and not ignored; they simply omit `🧬 Scope`.
-
-## Architecture Evolution
-
-### Before (pre-v1.0.0)
-
-- Monolithic routing and execution concentrated in `index.ts` + `handlers.ts`.
-- Redundant tool surface (9 tools) increased agent/tool-selection ambiguity.
-- Inline JSON schemas and docs drift risk.
-- Environment checks leaked across runtime paths.
-- Snapshot state lacked robust fingerprint protection for model/provider changes.
-
-### After (v1.0.0+)
-
-- Lightweight bootstrap in `index.ts` with registry-based tool routing.
-- Hard-break 4-tool surface optimized for agent cognition.
-- Modular tool execution in `src/tools/*.ts` with a shared `ToolContext`.
-- Zod schemas as canonical source, converted to JSON Schema at runtime.
-- Snapshot `v3` + fingerprint compatibility gates for safe multi-provider usage.
-- Deterministic train-in-the-error messages for self-healing agent loops.
-- Search observability via structured telemetry.
-- `read_file` upgraded for context-density control (ranges + truncation guard).
-
-### Architectural Shape (Current)
-
-```text
+- Capability-driven execution via `CapabilityResolver`
+- Runtime-first `search_codebase` with explicit `scope`, `resultMode`, `groupBy`, and optional `debug` traces
+- First-class `call_graph` tool with deterministic node/edge sorting and TS/Python support
+- Snapshot v3 safety with index fingerprints and strict `requires_reindex` access gates
+- Deterministic train-in-the-error responses for incompatible or legacy index states
+- Query-time exclusion support with `.gitignore`-style matching
+- Structured search telemetry logs (`[TELEMETRY]` JSON to `stderr`)
+- Zod-first tool schemas converted to MCP JSON Schema for `ListTools`
+- Auto-generated tool docs from live tool schemas
+- `read_file` line-range retrieval with default large-file truncation guard
+- Optional proactive sync watcher mode (debounced filesystem events)
+- Index-time AST scope breadcrumbs (TS/JS/Python) rendered in search output as `🧬 Scope`
+- Fingerprint schema `dense_v3`/`hybrid_v3` with hard gate for all pre-v3 indexes
+
+## Architecture
+
+```
 [MCP Client]
     -> [index.ts bootstrap + ListTools/CallTool]
     -> [tool registry]
-    -> [manage_index | search_codebase | read_file | list_codebases]
+    -> [manage_index | search_codebase | call_graph | read_file | list_codebases]
     -> [ToolContext DI]
        -> [CapabilityResolver]
        -> [SnapshotManager v3 + access gate]
        -> [Context / Vector store / Embedding / Reranker adapters]
 ```
 
-## Phase Summary
-
-- Phase 1 (state safety + API hard break):
-  - 9 tools -> 4 tools
-  - capability-driven behavior
-  - snapshot `v3` with index fingerprinting and strict reindex gating
-- Phase 2 (modularization + observability):
-  - tool registry and modular `src/tools/*`
-  - Zod-first schemas and generated docs
-  - structured search telemetry
-- Phase 3 (context density):
-  - `read_file` line-range semantics
-  - safe clamping for out-of-range requests
-  - `READ_FILE_MAX_LINES` truncation and continuation hints
-- Phase 5A (advanced context density, search-first):
-  - index-time AST breadcrumbs stored in chunk metadata (`breadcrumbs`)
-  - `search_codebase` scope rendering (`🧬 Scope: outer > inner`) across standard and rerank views
-  - fingerprint schema version bump to `*_v2` requiring reindex for `*_v1` snapshots
+Tool surface is hard-broken to 5 tools. This keeps routing explicit while exposing call-chain traversal as a first-class operation.
 
 ## read_file Behavior
 
-- Supports optional `start_line` and `end_line` (1-based, inclusive).
-- When no range is provided and file length exceeds `READ_FILE_MAX_LINES` (default `1000`), output is truncated and includes a continuation hint with `path` and next `start_line`.
+- Supports optional `start_line` and `end_line` (1-based, inclusive)
+- When no range is provided and file length exceeds `READ_FILE_MAX_LINES` (default `1000`), output is truncated and includes a continuation hint with `path` and next `start_line`
 
-## Proactive Sync (Optional)
+## Proactive Sync
 
-- Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable.
-- Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`).
-- Watch events reuse the same incremental sync pipeline (`reindexByChange`) and keep `manage_index(action="sync")` as explicit fallback.
+- Enabled by default. Set `MCP_ENABLE_WATCHER=false` to disable
+- Debounce window via `MCP_WATCH_DEBOUNCE_MS` (default `5000`)
+- Watch events reuse the same incremental sync pipeline (`reindexByChange`)
 - Safety gates:
-  - watch-triggered sync only runs for `indexed`/`sync_completed` codebases.
-  - events are dropped for `indexing`, `indexfailed`, and `requires_reindex`.
-  - ignored/hidden paths are excluded to avoid watcher explosion (`node_modules`, `.git`, build artifacts, dotfiles).
-- On shutdown (`SIGINT`/`SIGTERM`), watchers are explicitly closed.
-
-## Future Plan
-
-### 1) Agent Context Density
-
-- Add optional `read_file` paging ergonomics beyond current line ranges (for very large files/workflows).
-- Explore syntax-aware snippet shaping in `search_codebase` so results preserve function/class boundaries more reliably.
-
-### 2) Proactive Sync
-
-- Introduce optional filesystem watching with debounce for near-real-time incremental indexing.
-- Keep manual `manage_index(action="sync")` as explicit fallback.
-
-### 3) Provider Expansion
-
-- Extend reranker adapters (for example, Cohere) behind the same capability model.
-- Evaluate local vector-store adapters to support fully offline deployments.
-
-### 4) Observability Productization
-
-- Expand telemetry consumption into a local stats/report workflow (latency, reranker utilization, filter/drop rates).
-- Keep CI fast with deterministic unit/in-memory tests; run provider-backed integration checks on scheduled/manual workflows.
+  - Watch-triggered sync only runs for `indexed`/`sync_completed` codebases
+  - Events are dropped for `indexing`, `indexfailed`, and `requires_reindex`
+  - Ignored/hidden paths are excluded (`node_modules`, `.git`, build artifacts, dotfiles)
+- On shutdown (`SIGINT`/`SIGTERM`), watchers are explicitly closed
 
 <!-- TOOLS_START -->
 
@@ -132,32 +55,43 @@ Removed tools from pre-1.0 releases are no longer routed.
 
 ### `manage_index`
 
-Manage index lifecycle operations (create/sync/status/clear) for a codebase path.
+Manage index lifecycle operations (create/reindex/sync/status/clear) for a codebase path.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
-| `action` | enum("create", "sync", "status", "clear") | yes |  | Required operation to run. |
+| `action` | enum("create", "reindex", "sync", "status", "clear") | yes |  | Required operation to run. |
 | `path` | string | yes |  | ABSOLUTE path to the target codebase. |
 | `force` | boolean | no |  | Only for action='create'. Force rebuild from scratch. |
 | `splitter` | enum("ast", "langchain") | no |  | Only for action='create'. Code splitter strategy. |
 | `customExtensions` | array<string> | no |  | Only for action='create'. Additional file extensions to include. |
 | `ignorePatterns` | array<string> | no |  | Only for action='create'. Additional ignore patterns to apply. |
+| `zillizDropCollection` | string | no |  | Only for action='create'. Zilliz-only: drop this Satori-managed collection before creating the new index. |
 
 ### `search_codebase`
 
-Unified semantic search tool. Supports optional reranking and query-time excludes. Reranker is available. If useReranker is omitted, reranking is enabled automatically for fast/standard profiles.
+Unified semantic search with runtime/docs scope control, grouped/raw output modes, deterministic ranking, and structured freshness decision.
 
 | Parameter | Type | Required | Default | Description |
 |---|---|---|---|---|
 | `path` | string | yes |  | ABSOLUTE path to an indexed codebase or subdirectory. |
 | `query` | string | yes |  | Natural-language query. |
-| `limit` | integer | no | `50` | Maximum results to return. |
-| `extensionFilter` | array<string> | no | `[]` | Optional file-extension filter (e.g. ['.ts','.py']). |
-| `useIgnoreFiles` | boolean | no | `true` | Apply repo ignore files at search-time. |
-| `excludePatterns` | array<string> | no | `[]` | Optional query-time exclude patterns. |
-| `returnRaw` | boolean | no | `false` | Return machine-readable JSON results. |
-| `showScores` | boolean | no | `false` | Include similarity scores in formatted output. |
-| `useReranker` | boolean | no |  | Optional override: true=force rerank, false=disable rerank, omitted=resolver default. |
+| `scope` | enum("runtime", "mixed", "docs") | no | `"runtime"` | Search scope policy. runtime excludes docs/tests, docs returns docs/tests only, mixed includes all. |
+| `resultMode` | enum("grouped", "raw") | no | `"grouped"` | Output mode. grouped returns merged search groups, raw returns chunk hits. |
+| `groupBy` | enum("symbol", "file") | no | `"symbol"` | Grouping strategy in grouped mode. |
+| `limit` | integer | no | `50` | Maximum groups (grouped mode) or chunks (raw mode). |
+| `debug` | boolean | no | `false` | Optional debug payload toggle for score and fusion breakdowns. |
+
+### `call_graph`
+
+Traverse the prebuilt TS/Python call graph sidecar for callers/callees/bidirectional symbol relationships.
+
+| Parameter | Type | Required | Default | Description |
+|---|---|---|---|---|
+| `path` | string | yes |  | ABSOLUTE path to the indexed codebase root (or subdirectory). |
+| `symbolRef` | object | yes |  | Symbol reference from a grouped search result callGraphHint. |
+| `direction` | enum("callers", "callees", "both") | no | `"both"` | Traversal direction from the starting symbol. |
+| `depth` | integer | no | `1` | Traversal depth (max 3). |
+| `limit` | integer | no | `20` | Maximum number of returned edges. |
 
 ### `read_file`
 
@@ -178,23 +112,56 @@ No parameters.
 
 <!-- TOOLS_END -->
 
-## Run Locally
+## MCP Config Examples
 
-```bash
-pnpm --filter @zokizuan/satori-mcp start
+### JSON-style (Claude Desktop, Cursor)
+
+```json
+{
+  "mcpServers": {
+    "satori": {
+      "command": "npx",
+      "args": ["-y", "@zokizuan/satori-mcp@latest"],
+      "timeout": 180000,
+      "env": {
+        "EMBEDDING_PROVIDER": "VoyageAI",
+        "EMBEDDING_MODEL": "voyage-4-large",
+        "EMBEDDING_OUTPUT_DIMENSION": "1024",
+        "VOYAGEAI_API_KEY": "your-api-key",
+        "VOYAGEAI_RERANKER_MODEL": "rerank-2.5",
+        "MILVUS_ADDRESS": "your-milvus-endpoint",
+        "MILVUS_TOKEN": "your-milvus-token"
+      }
+    }
+  }
+}
+```
+
+### TOML-style (Claude Code CLI)
+
+```toml
+[mcp_servers.satori]
+command = "npx"
+args = ["-y", "@zokizuan/satori-mcp@latest"]
+startup_timeout_ms = 180000
+env = { EMBEDDING_PROVIDER = "VoyageAI", EMBEDDING_MODEL = "voyage-4-large", EMBEDDING_OUTPUT_DIMENSION = "1024", VOYAGEAI_API_KEY = "your-api-key", VOYAGEAI_RERANKER_MODEL = "rerank-2.5", MILVUS_ADDRESS = "your-milvus-endpoint", MILVUS_TOKEN = "your-milvus-token" }
 ```
 
-## Example MCP Configuration
+### Local development (when working on this repo)
 
 ```json
 {
   "mcpServers": {
     "satori": {
-      "command": "npx",
-      "args": ["@zokizuan/satori-mcp@latest"],
+      "command": "node",
+      "args": ["/absolute/path/to/claude-context/packages/mcp/dist/index.js"],
+      "timeout": 180000,
       "env": {
         "EMBEDDING_PROVIDER": "VoyageAI",
+        "EMBEDDING_MODEL": "voyage-4-large",
+        "EMBEDDING_OUTPUT_DIMENSION": "1024",
         "VOYAGEAI_API_KEY": "your-api-key",
+        "VOYAGEAI_RERANKER_MODEL": "rerank-2.5",
         "MILVUS_ADDRESS": "your-milvus-endpoint",
         "MILVUS_TOKEN": "your-milvus-token"
       }
@@ -203,6 +170,14 @@ pnpm --filter @zokizuan/satori-mcp start
 }
 ```
 
+Never commit real API keys/tokens into repo config files.
+
+## Run Locally
+
+```bash
+pnpm --filter @zokizuan/satori-mcp start
+```
+
 ## Development
 
 ```bash

package/dist/config.d.ts

@@ -6,7 +6,7 @@ export interface IndexFingerprint {
     embeddingModel: string;
     embeddingDimension: number;
     vectorStoreProvider: VectorStoreProvider;
-    schemaVersion: 'dense_v2' | 'hybrid_v2';
+    schemaVersion: 'dense_v3' | 'hybrid_v3';
 }
 export interface ContextMcpConfig {
     name: string;
@@ -28,6 +28,15 @@ export interface ContextMcpConfig {
     watchSyncEnabled?: boolean;
     watchDebounceMs?: number;
 }
+export interface CallGraphSidecarInfo {
+    version: 'v3';
+    sidecarPath: string;
+    builtAt: string;
+    nodeCount: number;
+    edgeCount: number;
+    noteCount: number;
+    fingerprint: IndexFingerprint;
+}
 export interface CodebaseSnapshotV1 {
     indexedCodebases: string[];
     indexingCodebases: string[] | Record<string, number>;
@@ -38,6 +47,7 @@ interface CodebaseInfoBase {
     indexFingerprint?: IndexFingerprint;
     fingerprintSource?: FingerprintSource;
     reindexReason?: 'legacy_unverified_fingerprint' | 'fingerprint_mismatch' | 'missing_fingerprint';
+    callGraphSidecar?: CallGraphSidecarInfo;
 }
 export interface CodebaseInfoIndexing extends CodebaseInfoBase {
     status: 'indexing';

package/dist/config.js

@@ -35,9 +35,9 @@ export function getEmbeddingModelForProvider(provider) {
 function getSchemaVersionFromEnv() {
     const hybridModeRaw = envManager.get('HYBRID_MODE');
     if (!hybridModeRaw) {
-        return 'hybrid_v2';
+        return 'hybrid_v3';
     }
-    return hybridModeRaw.toLowerCase() === 'true' ? 'hybrid_v2' : 'dense_v2';
+    return hybridModeRaw.toLowerCase() === 'true' ? 'hybrid_v3' : 'dense_v3';
 }
 export function buildRuntimeIndexFingerprint(config, embeddingDimension) {
     return {

package/dist/core/call-graph.d.ts

@@ -0,0 +1,116 @@
+import { CallGraphSidecarInfo, IndexFingerprint } from '../config.js';
+export type CallGraphDirection = 'callers' | 'callees' | 'both';
+export type CallGraphEdgeKind = 'call' | 'import' | 'dynamic';
+export interface CallGraphSpan {
+    startLine: number;
+    endLine: number;
+}
+export interface CallGraphSymbolRef {
+    file: string;
+    symbolId: string;
+    symbolLabel?: string;
+    span?: CallGraphSpan;
+}
+export interface CallGraphNode {
+    symbolId: string;
+    symbolLabel?: string;
+    file: string;
+    language: string;
+    span: CallGraphSpan;
+}
+export interface CallGraphEdge {
+    srcSymbolId: string;
+    dstSymbolId: string;
+    kind: CallGraphEdgeKind;
+    site: {
+        file: string;
+        startLine: number;
+        endLine?: number;
+    };
+    confidence: number;
+}
+export interface CallGraphNote {
+    type: 'unresolved_edge' | 'dynamic_edge' | 'missing_symbol_metadata';
+    file: string;
+    startLine: number;
+    symbolId?: string;
+    detail: string;
+}
+interface CallGraphSidecar {
+    formatVersion: 'v3';
+    codebasePath: string;
+    builtAt: string;
+    fingerprint: IndexFingerprint;
+    nodes: CallGraphNode[];
+    edges: CallGraphEdge[];
+    notes: CallGraphNote[];
+}
+export interface CallGraphResponseUnsupported {
+    supported: false;
+    reason: string;
+    hints?: Record<string, unknown>;
+}
+export interface CallGraphResponseSupported {
+    supported: true;
+    direction: CallGraphDirection;
+    depth: number;
+    limit: number;
+    nodes: CallGraphNode[];
+    edges: CallGraphEdge[];
+    notes: CallGraphNote[];
+    sidecar: {
+        builtAt: string;
+        nodeCount: number;
+        edgeCount: number;
+    };
+}
+export type CallGraphQueryResponse = CallGraphResponseSupported | CallGraphResponseUnsupported;
+export interface CallGraphDeltaPolicy {
+    shouldRebuild(changedFiles: string[]): boolean;
+}
+export declare class SupportedSourceDeltaPolicy implements CallGraphDeltaPolicy {
+    shouldRebuild(changedFiles: string[]): boolean;
+}
+export declare class CallGraphSidecarManager {
+    private readonly runtimeFingerprint;
+    private readonly splitter;
+    private readonly now;
+    private readonly deltaPolicy;
+    constructor(runtimeFingerprint: IndexFingerprint, options?: {
+        now?: () => number;
+        deltaPolicy?: CallGraphDeltaPolicy;
+    });
+    shouldRebuildForDelta(changedFiles: string[]): boolean;
+    loadSidecar(codebasePath: string): CallGraphSidecar | null;
+    rebuildForCodebase(codebasePath: string, ignorePatterns?: string[]): Promise<CallGraphSidecarInfo>;
+    rebuildIfSupportedDelta(codebasePath: string, changedFiles: string[], ignorePatterns?: string[]): Promise<CallGraphSidecarInfo | null>;
+    queryGraph(codebasePath: string, symbolRef: CallGraphSymbolRef, options: {
+        direction: CallGraphDirection;
+        depth: number;
+        limit: number;
+    }): CallGraphQueryResponse;
+    private buildGraph;
+    private buildSymbolIndex;
+    private resolveTargetNode;
+    private extractImportNames;
+    private extractCallSites;
+    private looksLikeDefinition;
+    private shouldScanNodeAsSource;
+    private extractSymbolNames;
+    private resolveConfidence;
+    private upsertNode;
+    private stripInlineComments;
+    private getSplitLanguage;
+    private isSupportedQueryLanguage;
+    private collectSourceFiles;
+    private getSidecarPath;
+    private toRelativePath;
+    private getEdgeKey;
+    private sortNodes;
+    private sortEdges;
+    private sortNotes;
+    private compareNullableNumbersAsc;
+    private compareNullableStringsAsc;
+}
+export {};
+//# sourceMappingURL=call-graph.d.ts.map