ttsc 维护者 Wiki

    代码图谱 MCP 服务器

    @ttsc/graph（packages/graph）把 internal/graph 构建的图通过 MCP 暴露给编码代理。本页讲 MCP 服务器的工具表面如何用 typia 从 TypeScript 接口反射生成、查询模型、以及与原生图谱构建的连接。源码 packages/graph/src/server/、packages/graph/src/structures/。

    typia 反射的工具表面（零手写 schema）

    createServer（packages/graph/src/server/createServer.ts:27）的核心是：

    const controller = typia.llm.controller<ITtscGraphApplication>(
  "graph",
  new TtscGraphApplication(graph),
);

    typia.llm.controller 把 ITtscGraphApplication 接口反射成一个已校验的工具应用：每个工具的 JSON schema 与参数校验器从方法的 TypeScript 类型与 JSDoc 生成——没有手写 schema（createServer.ts:13 注释）。这本身就是 ttsc 插件能力（typia 是 transform 插件）的 dogfooding：graph 用 typia 生成自己的 MCP 契约。

    注册刻意内联（不从 @typia/mcp 拉），把依赖面收到 typia + MCP SDK，避免 pin 整个 typia 生态版本。ListTools 列生成的函数，CallTool 校验参数（失败把 typia 的校验错误交回让模型自我纠正）再调方法。

    单工具、强引导的查询模型

    ITtscGraphApplication（structures/ITtscGraphApplication.ts:15）只有一个方法 query，即一个 MCP 工具。它的参数对象经反射成 JSON schema。

    设计有意把代理推向"少调用、小切片"：

    • 参数按顺序填：question（重述代码问题）、graphNeed（为什么图是下一证据源）、draft（先定操作类型）、review（批判草稿、避免 overfetch）、request（最终操作）。
    • 多数答案 1-3 次调用；四次是硬上限。
    • 鼓励小切片、用默认、一旦 file/symbol/range evidence 够了就停。

    request 是六种操作的判别联合：

    操作用途
    entrypoints（ITtscGraphEntrypoints）找入口/导出表面
    lookup（ITtscGraphLookup）查某符号相关的
    trace（ITtscGraphTrace）追调用链/依赖路径
    details（ITtscGraphDetails）某节点的细节
    overview（ITtscGraphOverview）项目概览
    escape（ITtscGraphEscape）no-op 逃逸（图不是对的源时）

    result.type 镜像 request.type。

    诊断融合

    README（packages/graph/README.md）强调一个超越纯图谱的能力：@ttsc/graph 携带项目的完整诊断——类型错误、@ttsc/lint 违规、插件 finding——融合到图上。所以代理在编辑前能看到一个改动在"已经坏掉的东西"之上的波及范围。这把图从"静态引用地图"升级成"带实时健康状态的地图"。

    常驻图与服务器

    packages/graph/src/server/ 的其他文件实现各操作（runLookup.ts、runTrace.ts、runDetails.ts、runOverview.ts、runEntrypoints.ts）与服务器生命周期（startServer.ts、createServer.ts）。TtscGraphMemory（model/）持有常驻图，resolveHandle.ts / accessAliases.ts 处理句柄解析。

    图本身来自原生 ttscgraph dump（cmd/ttscgraph）产出的 JSON，由 internal/graph 构建（见 构建与解析）。所以 MCP 服务器是 JS 薄壳，重活在 Go 原生图谱构建里。

    3D 查看器

    npx @ttsc/graph view（src/view.ts + src/viewer/）在本地端口起一个 3D 图查看器（three + three-forcegraph），按 kind 着色。src/viewer/main.ts 是查看器入口，index.html 是壳。README 展示了 TypeORM 在 3D 里的样子。

    CLI 入口

    命令作用
    npx @ttsc/graph起 MCP 服务器（代理用）
    npx @ttsc/graph view起 3D 查看器
    ttscgraph dump（原生）dump 图为 JSON

    MCP 配置（如 Claude Code 的 .mcp.json）指向 npx -y @ttsc/graph，代理从 MCP 握手自动拾取工具。

    不变量

    • 工具 schema 完全由 typia 从 TS 接口生成，无手写 schema。
    • 单工具 query，强引导参数填写顺序，四次调用硬上限。
    • 图来自原生 dump，JS 侧是薄壳。
    • 诊断融合让代理看到改动在已坏状态上的波及。

    维护者提示

    • 改工具表面 = 改 ITtscGraphApplication 及其子结构的 TypeScript 类型与 JSDoc；schema 自动跟随。别手写 JSON schema。
    • 加操作类型 = 在 request 联合加一个 IRequest、实现对应 run*.ts、加 IResult 成员。
    • 校验失败把 typia 错误交回模型，别吞——这是模型自我纠正的机制。

    接下来