How do I use @nlspec/server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@@nlspec/server list functions in the kv-store spec" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

@nlspec/server

by sddiv

Overview Schema Related Servers Score Discussions

TypeScript

Local

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.

Related MCP server: MCP SpecNavigator

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

On startup, the server scans specs/ for *-spec.md files
Each file is parsed into structured SpecElement objects — detecting types, extracting references (USES, THROWS, USED BY), tags ([SEC:x.x]), and preserving raw markdown
Elements are indexed in SQLite with FTS5 for full-text search
MCP tools expose CRUD + search over this index
Write operations (create/update/delete) modify both the SQLite index and the markdown file atomically
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

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

–Release cycle

–Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly
Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
OpenAI
open source

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sddiv/NLSpec-MCPServer_Old'

If you have feedback or need assistance with the MCP directory API, please join our Discord server