mcp-server-inverspec

An MCP (Model Context Protocol) server that guides AI assistants through reverse-engineering a technical specification from an undocumented codebase — the Inverspec workflow.

Supported stacks: Rails, Laravel, PHP+Smarty, Next.js, Express, Spring Boot, FastAPI, Flask, Django, and any other framework the AI can read.

---

Plans

Phase	Tool	Free	Pro
0	inverspec_phase_0_inventory	✅ full	✅ full
1	inverspec_phase_1_architecture	✅ full	✅ full
2	inverspec_phase_2_data_model	✅ full	✅ full
3	inverspec_phase_3_features	preview	✅ full
4	inverspec_phase_4_business_logic	preview	✅ full
5	inverspec_phase_5_operations	preview	✅ full
6	inverspec_phase_6_integration	preview	✅ full
7	inverspec_phase_7_maintenance	-	✅ full

Pro: $19/month or $190/year (2 months free) — Get a license: https://inverspec.lemonsqueezy.com

---

Quick start

For macOS users: npx may fail due to PATH conflicts on some systems (for example, ImageMagick's import command). We recommend the global npm installation below.

Claude Desktop — global npm install (recommended for macOS)

Step 1: Install globally

npm install -g mcp-server-inverspec

Step 2: Check the full binary path

which mcp-server-inverspec
# Example: /opt/homebrew/bin/mcp-server-inverspec
#     /usr/local/bin/mcp-server-inverspec

Step 3: Add it to claude_desktop_config.json

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "inverspec": {
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/mcp-server-inverspec/dist/index.js"]
    }
  }
}

Adjust the args path based on the output of which mcp-server-inverspec.
Example: if it shows /opt/homebrew/bin/mcp-server-inverspec, the actual file is
/opt/homebrew/lib/node_modules/mcp-server-inverspec/dist/index.js.

For Pro users (with license key):

{
  "mcpServers": {
    "inverspec": {
      "command": "node",
      "args": ["/opt/homebrew/lib/node_modules/mcp-server-inverspec/dist/index.js"],
      "env": {
        "INVERSPEC_LICENSE_KEY": "YOUR-LICENSE-KEY"
      }
    }
  }
}

---

Claude Desktop — npx (Linux / Windows)

Use this on non-macOS systems, or when no PATH conflicts occur:

{
  "mcpServers": {
    "inverspec": {
      "command": "npx",
      "args": ["-y", "mcp-server-inverspec"]
    }
  }
}

For Pro users:

{
  "mcpServers": {
    "inverspec": {
      "command": "npx",
      "args": ["-y", "mcp-server-inverspec"],
      "env": {
        "INVERSPEC_LICENSE_KEY": "YOUR-LICENSE-KEY"
      }
    }
  }
}

---

Cursor

Add this to .cursor/mcp.json:

{
  "mcpServers": {
    "inverspec": {
      "command": "npx",
      "args": ["-y", "mcp-server-inverspec"],
      "env": {
        "INVERSPEC_LICENSE_KEY": "YOUR-LICENSE-KEY"
      }
    }
  }
}

---

Claude Code (CLI)

claude mcp add inverspec -- npx -y mcp-server-inverspec

---

Usage

Important: Inverspec no longer provides filesystem tools. It returns phase prompt templates only. Saving generated documents is handled by your MCP client or by manual copy/paste.

Finding your project path

Inverspec requires the absolute path to your project root.

macOS / Linux — open a terminal, navigate to your project, and run pwd:

cd ~/Development/my-app
pwd
# → /Users/your-username/Development/my-app

Windows — open the folder in Explorer, then click the address bar to reveal the full path.

Can't find the path? You can also zip your project and upload it in clients that support file upload:

# macOS / Linux
cd ~/Development
zip -r my-app.zip my-app \
  --exclude "*/node_modules/*" \
  --exclude "*/.git/*" \
  --exclude "*/target/*"

---

Recommended prompt — run all phases in one go

Open a new chat in Claude Desktop and type:

Create a technical specification for /Users/your-username/Development/my-app.
Run Phase 0 through 6 without stopping for confirmation.
For each phase output, save it to docs/spec/ inside the project.

You can also run a single phase:

Run only Phase 2 (data model) on /Users/your-username/Development/my-app

---

How it works

Each phase tool accepts a projectPath and returns a detailed Markdown prompt template. The AI uses that template to analyze your project and generate phase documents. Inverspec does not read or write your files directly.

Phase	What gets documented
0	File tree, tech stack, scope boundary
1	Entry points, layers, request lifecycle, integrations
2	Entities, ER diagram(s) including domain-split layouts for large schemas, migrations, validation rules
3	Routes, API contracts, UI screens, webhooks
4	Domain rules, state machines, permissions, jobs
5	Config, deploy pipeline, observability, runbooks
6	Cross-references, glossary, executive summary

---

Output

After a full run, save the generated documents under:

docs/spec/ README.md - Executive summary and navigation guide 00-inventory.md - File tree, stack summary 01-architecture.md - Architecture map, request flow 02-data-model.md - ER diagram, entity sheets 03-features.md - API catalogue, feature cards 04-business-logic.md - Domain rules, state machines 05-operations.md - Config, deploy, observability

---

claude.ai vs Claude Desktop

Environment	Can run Inverspec MCP server	Recommended usage
Claude Desktop app	✅ Yes	Use local project path and save outputs manually
claude.ai (browser)	❌ No (MCP server not available)	Upload a zip and run prompts manually
Cursor	✅ Yes	Use local project path and save outputs manually
Claude Code (CLI)	✅ Yes	Use local project path and save outputs manually

---

Requirements

• Node.js 18 or later
• An MCP-compatible client (Claude Desktop, Cursor, Claude Code, etc.)

---

Feedback & Support

Found a bug or have a feature request? → Open an Issue

Have a question or idea to discuss? → Start a Discussion

---

License

ISC