AI导哈

自然语言规范解析服务

一个解析自然语言规范（nlspec）Markdown文件为结构化可查询元素的MCP服务器，提供CRUD和搜索操作。

  • by sddiv
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 sddiv/NLSpec-MCPServer

使用说明

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

由...生成 克劳德代码 使用 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_init 初始化新的nlspec项目或添加一个spec
nlspec_get 按ID读取特定元素或整个部分
nlspec_list 列出带有过滤器的元素（类型、部分、标签）
nlspec_search 全文搜索+结构化参考文献搜索
nlspec_create 向规范部分添加新元素
nlspec_update 修改现有元素的内容、标记或名称
nlspec_delete 拆下元件（参考安全检查）

例子

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

配置

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

变量 默认值 描述
NLSPEC_TRANSPORT "stdio" MCP传输类型
NLSPEC_PROJECT_DIR "." 项目的根目录
NLSPEC_INDEX_PATH ".nlspec/index.sqlite" SQLite索引路径（相对于project_dir）
NLSPEC_AUTO_REINDEX true markdown文件更改时重新解析
NLSPEC_FTS true 启用FTS5全文搜索

元素类型

解析器在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索引是在加载时从中重建的

依赖项

包装 用途
@modelcontextprotocol/sdk MCP服务器SDK（工具注册、stdio传输）
better-sqlite3 SQLite用于元素索引和FTS5全文搜索

许可证

麻省理工学院

相关 MCP