@nlspec/server

Retired this implementation to generate a new one at NLSpec-Server

Generated by Claude Code using NLSpec

@nlspec/server

MCP server that parses natural language specification (nlspec) markdown files into structured, queryable elements and exposes CRUD + search operations as MCP tools.

An AI coding agent connects via MCP and can read, create, update, delete, and search spec elements without parsing raw markdown itself.

Architecture

+-----------------------------------------------------------+
|                    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 files on disk are the source of truth. The SQLite index is a derived cache for fast queries and FTS5 full-text search. All mutations write back to markdown atomically (temp file + rename) and re-index.

Prerequisites

• Node.js 20+
• npm

Build

npm install
npm run build

Test

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

Usage

As an MCP Server

Add to your MCP client configuration:

Claude Code (.mcp.json in project root): ``json { "mcpServers": { "nlspec": { "command": "npx", "args": ["@nlspec/server"] } } } ``

Claude Desktop (claude_desktop_config.json): ``json { "mcpServers": { "nlspec": { "command": "npx", "args": ["@nlspec/server", "--project-dir", "/path/to/project"] } } } ``

Or run directly: ``bash npx @nlspec/server --project-dir /path/to/project ``

As a 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 Tools

| Tool | Description | |---|---| | nlspec_init | Initialize a new nlspec project or add a spec | | nlspec_get | Read a specific element by ID or an entire section | | nlspec_list | List elements with filters (type, section, tags) | | nlspec_search | Full-text search + structural reference search | | nlspec_create | Add a new element to a spec section | | nlspec_update | Modify an existing element's content, tags, or name | | nlspec_delete | Remove an element (with reference-safety check) |

Examples

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

Configuration

All settings can be set via environment variables:

| Variable | Default | Description | |---|---|---| | NLSPEC_TRANSPORT | "stdio" | MCP transport type | | NLSPEC_PROJECT_DIR | "." | Root directory of the project | | NLSPEC_INDEX_PATH | ".nlspec/index.sqlite" | SQLite index path (relative to project_dir) | | NLSPEC_AUTO_REINDEX | true | Re-parse when markdown files change | | NLSPEC_FTS | true | Enable FTS5 full-text search |

Element Types

The parser recognizes these element types inside code fence blocks in spec markdown:

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

How It Works

1. On startup, the server scans specs/ for *-spec.md files
2. Each file is parsed into structured SpecElement objects — detecting types, extracting references (USES, THROWS, USED BY), tags ([SEC:x.x]), and preserving raw markdown
3. Elements are indexed in SQLite with FTS5 for full-text search
4. MCP tools expose CRUD + search over this index
5. Write operations (create/update/delete) modify both the SQLite index and the markdown file atomically
6. The markdown file is always the source of truth — the SQLite index is rebuilt from it on load

Dependencies

| Package | Purpose | |---|---| | @modelcontextprotocol/sdk | MCP server SDK (tool registration, stdio transport) | | better-sqlite3 | SQLite for element index and FTS5 full-text search |

License

MIT