codenexus-mcp | 通往MCP之路

代码库知识图谱 MCP 服务器

该服务器提供了一个专门用于与表示软件代码库的知识图谱交互的模型上下文协议（Model Context Protocol, MCP）接口。它允许存储和检索关于代码实体（类、函数、文件等）、它们之间的关系（调用、导入、实现等）以及相关的定性观察（如设计决策、模式使用、变更原因、注释等）的丰富结构化信息。

目标是构建一个全面的、可查询的代码库表示，超越静态分析，捕捉架构洞察和开发上下文。

服务器组件

server.js：运行 MCP 服务器的主要 Node.js 脚本。

memory.json：默认用于持久化知识图谱数据的文件。

安装与配置

安装依赖：

运行服务器：

服务器将在标准输入/输出上监听 MCP 请求。

持久化配置：

知识图谱默认持久化在与 server.js 同目录下的 memory.json 文件中。

该文件使用 JSON Lines (JSONL) 格式，每行是一个单独的 JSON 对象，表示一个实体或关系。

您可以通过在运行服务器前设置 MEMORY_FILE_PATH 环境变量来指定自定义的持久化文件路径：

知识图谱模式

该服务器存储和管理的图谱由三个主要组件组成：实体（Entities）、关系（Relations）和观察（Observations）。实体表示核心元素（代码结构、项目），关系定义它们之间的连接，观察则附加定性信息或元数据。

这些组件的详细结构在 server.js 中定义如下：

`Entity`

表示代码库或项目中的独立元素。

name（字符串，必需）：唯一标识符（如函数名、类名、文件路径）。

entityType（字符串，必需）：实体类型（如 'class', 'function', 'module', 'variable', 'file', 'project'）。

language（字符串，可选）：编程语言（如 'javascript', 'python'）。

filePath（字符串，可选）：包含实体的文件的相对路径。

startLine（数字，可选）：起始行号（从 1 开始）。

endLine（数字，可选）：结束行号（从 1 开始）。

signature（字符串，可选）：函数/方法的参数列表和返回类型。

summary（字符串，可选）：简要描述（如来自文档字符串）。

accessModifier（'public' | 'private' | 'protected'，可选）：语言特定的访问控制。

isStatic（布尔值，可选）：语言特定的静态标识符。

isAsync（布尔值，可选）：语言特定的异步标识符。

namespace（字符串，可选）：模块或命名空间。

tags（字符串数组，可选）：用户定义的分类标签。

observations（Observation[]，必需）：与此实体关联的观察对象数组（如果未提供，则初始化为空数组）。

metadata（Record<string, any>，可选）：其他自定义或工具特定的数据。

`ProjectEntity`

一种特定类型的 Entity（entityType: 'project'），用于存储项目本身的高级信息。

name（字符串，必需）：项目的唯一名称/标识符（如 'my-web-app'）。

entityType（'project'，必需）：必须为 'project'。

description（字符串，可选）：项目的高级描述。

technologies（字符串数组，可选）：使用的关键技术列表（如 ['React', 'Node.js', 'PostgreSQL']）。

architectureStyle（字符串，可选）：整体架构（如 'Microservices', 'Monolith', 'Serverless'）。

repositoryUrl（字符串，可选）：代码仓库的 URL。

observations（Observation[]，必需）：项目本身的相关观察（如高级设计决策、路线图链接）。

metadata（Record<string, any>，可选）：其他自定义项目特定数据。

`Relation`

表示两个实体之间的有向关系。

from（字符串，必需）：源实体的名称。

to（字符串，必需）：目标实体的名称。

relationType（字符串，必需）：关系类型（如 'CALLS', 'IMPLEMENTS', 'IMPORTS', 'CONTAINS'）。

filePath（字符串，可选）：关系发生/定义的文件。

line（数字，可选）：关系发生的行号（从 1 开始）。

contextSnippet（字符串，可选）：说明关系的小代码片段。

metadata（Record<string, any>，可选）：其他自定义或工具特定的数据。

`Observation`

表示附加到实体的定性信息或元数据。

id（字符串，必需）：观察的唯一 ID（如果未提供，则自动生成 UUID）。

observationType（字符串，必需）：观察类型。标准类型包括：

'design_pattern_use'：描述设计模式的使用。建议的 metadata：{ patternName: string, role?: string }。
'design_decision'：记录特定的设计选择。建议的 metadata：{ rationale?: string, alternativesConsidered?: string[], decisionMaker?: string, relatedIssue?: string }。
'change_rationale'：解释代码变更的原因。建议的 metadata：{ commitHash?: string, author?: string, relatedIssue?: string, summaryOfChange?: string }。
'project_meta'：存储项目级别的元数据（通常附加到 'Project' 实体）。建议的 metadata 取决于具体信息（如 { repositoryUrl: string, primaryTechnology: string }）。
其他常见类型：'comment', 'todo', 'fixme', 'security_note', 'performance_note'。

content（字符串，必需）：观察的主要内容/文本。

filePath（字符串，可选）：与观察相关的文件。

line（数字，可选）：与观察相关的行号（从 1 开始）。

severity（'high' | 'medium' | 'low' | 'info'，可选）：严重级别。

source（字符串，可选）：来源（如 'static_analysis', 'human_annotator', 'llm', 'code_comment'）。

timestamp（字符串，可选）：ISO 8601 时间戳（如 new Date().toISOString()）。

author（字符串，可选）：创建观察的人/工具。

relatedEntities（字符串数组，可选）：其他相关实体的名称。

metadata（Record<string, any>，可选）：其他自定义数据。有关标准类型的建议字段，请参见 observationType。

API 工具参考

服务器通过模型上下文协议（MCP）暴露以下工具。每个工具的输入对应于 MCP CallToolRequest 中的 arguments 字段。

`create_entities`

用途： 在知识图谱中创建一个或多个新实体。如果具有相同 name 的实体已存在，则忽略。

参数：

输出： 返回成功创建的实体数组的 JSON 字符串表示。

`create_relations`

用途： 在现有实体之间创建一个或多个新关系。重复的关系将被忽略。

参数：

输出： 返回成功创建的关系数组的 JSON 字符串表示。

`add_observations`

用途： 向现有实体添加观察。如果目标实体不存在，则失败。如果缺少 ID，则分配唯一 ID。对于同一实体，忽略具有重复 ID 的观察。

参数：

输出： 返回结果的 JSON 字符串表示，显示每个实体添加的观察。

`delete_entities`

用途： 移除实体及其连接的关系。

参数：

输出： 确认消息。

`delete_observations`

用途： 通过 ID 从实体中移除特定观察。

参数：

输出： 确认消息。

`delete_relations`

用途： 移除特定关系。

参数：

输出： 确认消息。

`read_graph`

用途： 检索整个图谱。

参数： 无（或 {}）。

输出： 图谱的 JSON 字符串：{ "entities": [...], "relations": [...] }。

`search_nodes`

用途： 基于查询字符串搜索实体（检查名称、类型、观察、元数据等）。

参数：

输出： 过滤后的图谱的 JSON 字符串（匹配的实体及其之间的关系）。

`open_nodes`

用途： 按名称检索特定实体及其之间的关系。

参数：

输出： 过滤后的图谱的 JSON 字符串（请求的实体及其之间的关系）。

使用示例

以下是常见操作的 MCP CallToolRequest 的 arguments 部分示例：

1. 创建项目实体

使用 create_entities，entityType 设为 'project'：

2. 创建函数实体

使用 create_entities，entityType 设为 'function'：

3. 添加设计决策观察

使用 add_observations。注意结构：observationsInput 是一个数组，包含每个待更新实体的对象。每个对象指定 entityName 和一个 observationsToAdd 数组。

4. 添加设计模式使用观察

使用 add_observations：

5. 添加变更原因观察

使用 add_observations：

6. 创建关系

使用 create_relations 连接两个现有实体（如 OrderProcessor 调用 calculateTotalAmount）：

与 NPX / 客户端集成使用

NPX

以下命令下载并运行服务器的最新版本：

（注意：VS Code 在 settings.json 或 .vscode/mcp.json 中使用稍有不同的结构）

NPX 自定义配置

可以使用 MEMORY_FILE_PATH 环境变量配置服务器，以指定知识图谱数据文件的自定义位置。

（注意：以下为 VS Code 的 settings.json 示例）

许可证

该项目目前未授权。请在此处添加适当的许可证信息（如 MIT 许可证），并在适用时包含 LICENSE 文件。