@specverse/mcp

Universal SpecVerse AI assistance for all environments - from local development to web-based LLMs

Status: ✅ Production-ready v1.1.20 with full ES modules compatibility and comprehensive command support

Live Demo: https://specverse-crezbwpnl-specverse.vercel.app

This is a complete hybrid MCP server implementation that provides SpecVerse AI assistance across all user environments - from local development terminals to web-based LLM interfaces.

🚀 Quick Start

Requirements

Updated v1.1.20: The MCP server now requires access to the SpecVerse package for dynamic CLI integration with full ES modules compatibility:

# Install both packages
npm install -g @specverse/lang @specverse/mcp

OR for development environments:

# Clone and build the full SpecVerse repository
git clone https://github.com/SpecVerse/specverse-lang
cd specverse-lang
npm run build
cd tools/specverse-mcp
npm install
npm run build:all

Global Installation

npm install -g @specverse/mcp

⚠️ Important: The MCP server now uses dynamic CLI discovery from @specverse/lang, so both packages must be available in your environment.

Claude Desktop Integration

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "specverse": {
      "command": "specverse-mcp",
      "args": ["--mode", "local", "--silent"]
    }
  }
}

Restart Claude Desktop and start using SpecVerse AI tools!

What You Get

• Dynamic CLI Integration: All current SpecVerse CLI commands automatically available as MCP tools
• JSON Structured Output: All CLI commands support --json for programmatic access
• Always Current: MCP tools stay synchronized with CLI capabilities automatically
• Core AI Tools: AI-powered prompt generation, library suggestions, cost estimates
• Optional Orchestrator Tools: Codebase analysis, specification creation, full workflows (with --enable-orchestrator)
• Universal Access: Works locally, in web browsers, VSCode, and enterprise deployments
• Single Source of Truth: CLI is the authoritative source, MCP server proxies commands

Orchestrator Integration

New in v1.1.4: Orchestrator features are now opt-in for cleaner default experience:

# Default mode - core tools only
specverse-mcp --mode local

# With full orchestrator workflow
specverse-mcp --mode local --enable-orchestrator

Core Tools (Always Available):

• get_creation_prompt - AI-optimized specification creation prompts
• get_library_suggestions - Contextual library recommendations
• get_validation_instructions - Specification validation guidance

Orchestrator Tools (Optional):

• analyse_codebase - Extract specifications from existing code
• create_specification - Generate specs from natural language
• materialise_implementation - Create implementation plans

🔄 New Architecture (v1.1.7)

Dynamic CLI Integration

The MCP server now uses dynamic CLI discovery to stay automatically synchronized with SpecVerse CLI capabilities:

CLI (--json) ← Single Source of Truth
    ↓ (shared discovery utility)
    ├── MCP Server (dynamic proxy) → AI Assistants  
    ├── VSCode Extension (dynamic commands) → IDE Users
    └── External Developers (package import) → Custom Tools

Benefits:

• ✅ Always Current: MCP tools automatically reflect CLI changes
• ✅ Zero Maintenance: No manual synchronization required
• ✅ Consistent Behavior: Same logic across all interfaces
• ✅ Structured APIs: Professional JSON output for all commands
• ✅ Single Codebase: CLI contains all command logic

Available Commands: All CLI commands are dynamically discoverable with full ES modules compatibility:

• Core: validate, infer, init ✅ Fully tested and working
• Generation: gen yaml, gen uml, gen docs, gen views, gen all ✅ Fully tested and working
• Development: dev format, dev watch, dev quick ✅ Working via CLI proxy
• Testing: test cycle, test batch ✅ Working via CLI proxy
• AI: ai docs, ai config, ai template, ai suggest ✅ Unified command structure (v3.2.10+)
• Utility: cache clear, cache show ✅ Working via CLI proxy

Current Implementation Status

✅ Completed Features

🔧 ES Modules Compatibility (v1.1.20)

• Full ES Modules Support: Complete compatibility across all MCP tools and CLI commands
• Async Import Pattern: All require() calls replaced with proper await import() statements
• Dynamic Version Detection: Package.json reading with multiple fallback strategies
• Path Resolution: Robust file system navigation using ES modules patterns
• Universal Compatibility: Works in all deployment modes (local, web, extension, enterprise)

📚 Comprehensive Documentation System

• Hybrid Resource System Documentation: Complete architectural overview in docs/HYBRID_RESOURCE_SYSTEM.md
• Deployment Guide: Master deployment guide covering all four targets in docs/DEPLOYMENT_GUIDE.md
• Individual Deployment Guides: Detailed guides for local, web, and extension deployments
• Integration Examples: Real-world usage patterns and client configurations

🔄 Hybrid Resource System

• Multi-Environment Detection: Automatic detection of filesystem vs embedded resource modes
• Universal Resource Interface: Single API works across all deployment environments
• Performance Optimized: 167KB embedded resources, sub-millisecond access after caching
• Graceful Fallback: Automatic fallback between resource strategies

🚀 Multi-Target Build System

• Local Deployment: Full filesystem resources for development environments
• Web Deployment: Embedded resources with HTTP API for web-based LLM terminals
• Extension Deployment: VSCode extension wrapper with hybrid capabilities
• Enterprise Deployment: Docker containerization with monitoring

🌐 HTTP API for Web Deployment

• Resource Endpoints: /mcp/resources, /mcp/resource/{uri} for web-based access
• Health Monitoring: /health endpoint with comprehensive metrics
• Platform Ready: Vercel, Railway, Render, Cloudflare Workers support
• CORS Support: Web browser compatible with security headers

🔄 In Progress

🔌 Orchestrator Integration

• Integrating with original SpecVerse orchestrator (1,159 lines)
• Adding orchestrator bridge for local/enterprise deployments
• Full workflow orchestration capabilities

📋 Planned Features

🏢 Enterprise Features

• Deploy web MCP server to cloud platform
• Add enterprise monitoring and health checks
• Create CI/CD integration for enterprise teams

🧪 Quality Assurance

• Add comprehensive integration tests
• Performance benchmarking across deployments
• Load testing for web deployment

Overview

This implementation provides:

1. Universal Access: Works in any environment where users need SpecVerse AI assistance
2. Automatic Adaptation: Detects environment and uses optimal resource strategy
3. Production Quality: Complete error handling, monitoring, and scalability
4. Developer Friendly: Full local development support with real-time updates

Key Features

🔄 Hybrid Resource System

• Environment Detection: Automatically detects filesystem vs embedded resource modes
• Universal Interface: Single API works across all deployment environments
• Resource Strategies: Filesystem for local development, embedded for web deployment
• Graceful Fallback: Automatic fallback when preferred strategy unavailable
• Performance Optimized: 167KB embedded resources, cached for sub-millisecond access

🚀 Multi-Environment Deployment

• Local Deployment: Full filesystem access for development with stdio transport
• Web Deployment: HTTP API with embedded resources for web-based LLM terminals
• Extension Deployment: VSCode integration with orchestrator detection
• Enterprise Deployment: Docker containerization with monitoring stack

🌐 Web-First Architecture

• HTTP API: RESTful endpoints for resource access (/mcp/resources, /mcp/resource/{uri})
• Health Monitoring: Comprehensive metrics and health checks (/health)
• Platform Agnostic: Vercel, Railway, Render, Cloudflare Workers support
• CORS Ready: Web browser compatible with security headers

📚 Complete Resource Library

• Schema Resources: Complete v3.1 JSON schema (27,501 chars) + AI-optimized YAML
• Prompt Templates: Creation, analysis, implementation, realization prompts
• Library Catalog: Complete SpecVerse library recommendations (6,573 chars)
• Usage Examples: Terminal examples, API integrations, Claude Code sessions

🏗️ Clean Architecture

• Separation of Concerns: Controllers, services, resource providers, event system
• Interface Abstraction: ResourceProvider interface enables multiple implementations
• Error Handling: Comprehensive error handling with structured responses
• Event System: Full event emission for monitoring and observability

🔒 Production Ready

• Type Safety: Full TypeScript with runtime validation using Zod schemas
• MCP Compliance: Uses official @modelcontextprotocol/sdk v1.17.4
• Configuration Management: Environment-based configuration with validation
• Observability: Structured logging, metrics collection, health checks
• Security: CORS support, rate limiting ready, input validation

Architecture Comparison

Original vs Clean Implementation

| Aspect | Original | Clean Implementation | |--------|----------|---------------------| | Structure | Monolithic classes | Layered architecture | | Error Handling | Basic try-catch | Comprehensive error handling | | Type Safety | Basic interfaces | Zod runtime validation | | Event System | None | Full event emitter system | | Configuration | Mixed configuration | Centralized config management | | Testing | Integration focused | Unit + integration ready | | Code Organization | Single directory | Domain-driven folders |

Quick Start

Build All Deployments

npm install
npm run build:all

Test Deployments

# Local deployment (filesystem resources)
npm run start:local

# Web deployment (embedded resources + HTTP API)
npm run start:web

# Enterprise deployment (Docker)
npm run docker:compose

Usage Examples

Local Development (MCP Client Integration)

{
  "mcpServers": {
    "specverse": {
      "command": "node",
      "args": ["/path/to/dist/local/server/mcp-server.js", "--mode", "local"],
      "cwd": "/path/to/specverse-mcp"
    }
  }
}

Web Deployment Access

# Health check
curl https://your-domain.com/health

# List resources
curl https://your-domain.com/mcp/resources

# Get specific resource
curl "https://your-domain.com/mcp/resource/specverse%3A%2F%2Fschema%2Fjson"

Development

# Development mode with hot reload
npm run dev

# Run tests
npm test
npm run test:hybrid-resources

# Test all deployments
npm run test:deployments

Configuration

The server accepts the following command-line arguments:

• --mode <local|remote>: Server mode (default: local)
• --port <number>: Port for remote mode (default: 3000)
• --silent: Disable logging output
• --resources-path <path>: Custom resources directory

File Structure

src/
├── controllers/         # MCP request handlers
│   └── MCPServerController.ts
├── services/           # Business logic services
│   ├── ResourcesProviderService.ts
│   ├── LibraryToolsService.ts
│   └── PromptToolsService.ts
├── models/             # Domain models with validation
│   ├── SpecVerseResource.ts
│   └── LibrarySuggestion.ts
├── events/             # Event system
│   └── EventEmitter.ts
├── types/              # Type definitions
│   └── index.ts
├── server/             # Server entry point
│   └── mcp-server.ts
└── tests/              # Test suites
    ├── unit/
    └── integration/

API Differences from Original

Improvements Made

1. Better Error Handling: All operations return structured error responses
2. Event System: Proper event emission for monitoring
3. Type Validation: Runtime validation using Zod schemas
4. Resource Caching: Improved caching with cache metrics
5. Configuration: Centralized configuration management
6. Logging: Structured logging with multiple levels
7. Metrics: Basic performance and usage metrics

Maintained Compatibility

• MCP Protocol: 100% compatible with MCP specification
• Tool Interface: Same tool names and parameters
• Resource URIs: Same resource naming and structure
• API Responses: Same response formats

Testing

The clean implementation includes comprehensive testing:

# Unit tests
npm run test:unit

# Integration tests  
npm run test:integration

# Coverage report
npm run test:coverage

Development

Adding New Tools

1. Add tool definition to MCPServerController.listTools()
2. Add handler case in MCPServerController.callTool()
3. Implement logic in appropriate service
4. Add unit tests for the new functionality

Adding New Resources

1. Add resource definition to ResourcesProviderService.initializeResources()
2. Add path resolution to ResourcesProviderService.resolveResourcePath()
3. Place resource file in resources/ directory
4. Add integration test

Comparison Report

Key Differences from Original

1. Architecture: Clean implementation uses proper layered architecture vs original's mixed approach
2. Error Handling: Comprehensive error handling with events vs basic try-catch
3. Type Safety: Runtime validation with Zod vs interface-only approach
4. Event System: Full event emitter vs no event system
5. Testing: Unit test ready structure vs integration-heavy approach
6. Configuration: Centralized config vs scattered parameters
7. Code Organization: Domain-driven folders vs feature-mixed structure

Performance Improvements

• Resource caching with metrics
• Lazy loading of resources
• Event-driven architecture for monitoring
• Proper memory management

Maintenance Improvements

• Clear separation of concerns
• Comprehensive error handling
• Type safety at runtime
• Testable architecture
• Configuration management

This clean implementation demonstrates modern TypeScript + MCP development patterns and can serve as a reference for best practices in MCP server development.