Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
Generated by Claude Code using NLSpec
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.
+-----------------------------------------------------------+
| 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
Node.js 20+
npm
npm install
npm run buildnpm test # all tests (21 scenarios)
npm run test:smoke # smoke only (scenarios 1, 2, 3)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/projectnpx nlspec init --name myservice
npx nlspec list --spec myservice --type FUNCTION
npx nlspec search "Entry" --type FUNCTION
npx nlspec get --spec myservice --section 5.1Tool | Description |
| Initialize a new nlspec project or add a spec |
| Read a specific element by ID or an entire section |
| List elements with filters (type, section, tags) |
| Full-text search + structural reference search |
| Add a new element to a spec section |
| Modify an existing element's content, tags, or name |
| Remove an element (with reference-safety check) |
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 fileAll settings can be set via environment variables:
Variable | Default | Description |
|
| MCP transport type |
|
| Root directory of the project |
|
| SQLite index path (relative to project_dir) |
|
| Re-parse when markdown files change |
|
| Enable FTS5 full-text search |
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
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
Package | Purpose |
| MCP server SDK (tool registration, stdio transport) |
| SQLite for element index and FTS5 full-text search |
MIT
This server cannot be deployed
Shared Markdown notes for MCP-compatible AI tools.
MCP-native collaborative markdown editor with real-time AI document editing
Your org's AI agents, tasks, runs, search, and brain files as MCP tools and resources.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
