Nl Spec MCP Server

停用此实现，以便在NLSpec服务器上生成新的实现

@nlspec/服务器

MCP服务器，将自然语言规范（nlspec）markdown文件解析为结构化、可查询的元素，并将CRUD+搜索操作作为MCP工具公开。

AI编码代理通过MCP连接，可以读取、创建、更新、删除和搜索规范元素，而无需解析原始markdown本身。

建筑

+-----------------------------------------------------------+
|                    MCP Clients                             |
|  (Claude Code, Cursor, Claude Desktop, any MCP client)    |
+---------------------------+-------------------------------+
                            | MCP Protocol (stdio)
                            v
+-----------------------------------------------------------+
|                   nlspec MCP Server                        |
|                                                            |
|  +-------------------+  +-------------------+             |
|  |  MCP Tool Layer   |  |  CLI Adapter      |             |
|  |  7 tools          |  |  (same functions) |             |
|  +---------+---------+  +---------+---------+             |
|            |                      |                        |
|            +----------+-----------+                        |
|                       |                                    |
|            +----------v-----------+                        |
|            |    Core Engine       |                        |
|            |                      |                        |
|            |  +----------------+  |                        |
|            |  | Spec Parser    |  | Markdown -> Elements   |
|            |  +----------------+  |                        |
|            |  +----------------+  |                        |
|            |  | Spec Store     |  | CRUD on Elements       |
|            |  +----------------+  |                        |
|            |  +----------------+  |                        |
|            |  | Query Engine   |  | Text + structural      |
|            |  +----------------+  | search                 |
|            |                      |                        |
|            +----------+-----------+                        |
|                       |                                    |
|            +----------v-----------+                        |
|            |  Persistence         |                        |
|            |  - .md files (truth) |                        |
|            |  - SQLite (index)    |                        |
|            +----------------------+                        |
+-----------------------------------------------------------+

磁盘上的Markdown文件是 真相之源SQLite索引是用于快速查询和FTS5全文搜索的派生缓存。所有突变都以原子方式写回markdown（临时文件+重命名）并重新索引。

先决条件

• Node.js 20+
• npm

构建

npm install
npm run build

测试

npm test                # all tests (21 scenarios)
npm run test:smoke      # smoke only (scenarios 1, 2, 3)

用法

作为MCP服务器

添加到MCP客户端配置中：

克劳德代码 (.mcp.json 在项目根目录中）：

{
  "mcpServers": {
    "nlspec": {
      "command": "npx",
      "args": ["@nlspec/server"]
    }
  }
}

克劳德桌面 (claude_desktop_config.json):

{
  "mcpServers": {
    "nlspec": {
      "command": "npx",
      "args": ["@nlspec/server", "--project-dir", "/path/to/project"]
    }
  }
}

或者直接运行：

npx @nlspec/server --project-dir /path/to/project

作为CLI

npx nlspec init --name myservice
npx nlspec list --spec myservice --type FUNCTION
npx nlspec search "Entry" --type FUNCTION
npx nlspec get --spec myservice --section 5.1

MCP工具

例子

nlspec_get({spec_id: "kv-store", section: "5.1"})
  -> Returns Section 5.1 with all FUNCTIONs

nlspec_search({references: "Entry", element_type: "FUNCTION"})
  -> Returns all FUNCTIONs that USES Entry

nlspec_list({spec_id: "kv-store", element_type: "SCENARIO", tags: ["SMOKE"]})
  -> Returns SMOKE-tagged scenarios

nlspec_create({spec_id: "kv-store", section: "10", element_type: "SCENARIO", ...})
  -> Adds a new SCENARIO to the spec and markdown file

配置

所有设置都可以通过环境变量进行设置：

元素类型

解析器在spec markdown中的代码围栏块内识别这些元素类型：

RECORD FUNCTION ENDPOINT SCENARIO ENUM ALIAS CONFIG IMAGE MANIFEST INFRA PIPELINE TOPOLOGY CONTRACT FAILURE_MODE IMPORT PROSE

运作原理

1. 启动时，服务器扫描 specs/ 为了 *-spec.md 文件
2. 每个文件都被解析为结构化 SpecElement 对象--检测类型、提取引用(USES, THROWS, USED BY)，标签([SEC:x.x])，并保留原始降价
3. 元素在SQLite中使用FTS5进行索引，以进行全文搜索
4. MCP工具在此索引上公开CRUD+搜索
5. 写入操作（创建/更新/删除）以原子方式修改SQLite索引和markdown文件
6. markdown文件始终是事实的来源——SQLite索引是在加载时从中重建的

依赖项

许可证

麻省理工学院