knocoph (Jagonzalr)

Knocoph

Knocoph（化名）是当地人 主控程序 该服务器将TypeScript和JavaScript代码库转换为存储在SQLite中的持久代码知识图。

Knocoph使人工智能助手不再贪婪地读取整个文件和燃烧上下文标记 结构化代码库导航 通过确定性图查询。使用近乎即时的响应和最小的令牌消耗来导航调用链、导入图、继承层次结构和符号依赖关系。

安装

全局安装，以便 knocoph 命令在PATH中可用：

npm install -g knocoph

配置MCP服务器

将Knocoph添加到MCP客户端配置中（例如。 .mcp.json, claude_desktop_config.json):

{
  "servers": {
    "knocoph": {
      "type": "stdio",
      "command": "knocoph",
      "env": {
        "knocoph_DB": "./.knocoph/graph.db",
        "knocoph_ROOT": "."
      }
    }
  }
}

两者 env 变量是 可选的 --Knocoph使用合理的默认值（如果省略）：

默认情况下的最小配置（否 env 需要块）：

{
  "servers": {
    "knocoph": {
      "type": "stdio",
      "command": "knocoph"
    }
  }
}

指导AI助手使用Knocoph

为了指导您的AI助手（Claude、Copilot等）有效地使用Knocoph MCP工具，而不是直接读取文件，请复制以下说明 MCP_USAGE.md 将AI助手的系统提示符AGENTS.md、CLAUDE.md或等效配置文件。

这些说明教会AI：

• 使用 find_symbol 打开文件之前
• 使用图查询来理解关系，而不是燃烧上下文标记
• 呼叫 explain_impact 在进行更改之前
• 使用 get_snippet 获取精确的代码范围，而不是整个文件

这种方法最大限度地减少了代币消耗，并提供了快速、准确的结构性答案。

特性

• 持久代码图 --将代码库解析为节点（符号）和边（关系），存储在SQLite中
• 自动标引 --文件监视器在代码更改时保持图形更新
• 零文件读取 --在不打开源文件的情况下查询结构化问题
• MCP工具 --7个针对不同勘探模式的专用查询工具
• 跨文件关系 --跟踪导入、导出、调用、继承和遏制
• TypeScript路径别名解析 --自动读取 tsconfig.json 解决 @scope/... 样式导入

运作原理

1. 解析 --TypeScript ESLint解析器从源文件中提取符号、类型和关系
2. 图 --为函数、类、接口、变量等构建节点。
3. 商店 --在SQLite中保留所有元数据和边
4. 查询 --通过MCP工具提供结构化答案，无需重新解析

MCP工具

TypeScript路径别名

如果您的项目使用 compilerOptions.paths 在 tsconfig.json （例如。 @myapp/*, @auth)，Knocoph会自动解析它们。当 index_project 被称为，它寻找 tsconfig.json 在项目根目录中读取 compilerOptions.paths 和 baseUrl 将别名导入解析为其真实文件路径。

标准设置不需要配置：

// tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@myapp/*": ["src/*"], // @myapp/utils → src/utils.ts
      "@auth": ["src/auth/index.ts"],
    },
  },
}

如果你的 tsconfig.json 如果不在项目根目录，请显式传递路径：

index_project { root_dir: ".", tsconfig_path: "./packages/app/tsconfig.json" }

支持的模式：简单前缀通配符(@scope/*)精确匹配(@auth).仅使用每个阵列中的第一个替换。跳过复杂的多通配符模式。

快速参考

# Install globally
npm install -g knocoph

# Run tests (contributors)
npm run test:ci

# Format and lint (contributors)
npm run prettier
npm run lint

设计原则

• 文件前的图形 --无需文件I/O即可回答结构问题
• 确定性查询 --相同的输入总是返回相同的结果
• 代币效率 --小而精确的响应，而不是完整的文件内容
• 简洁 --通过巧妙的抽象实现显式、可读的代码