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):

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

Claude Desktop (claude_desktop_config.json):

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

Or run directly:

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