@isl-lang/mcp-server

v0.2.0

Published

14 days ago

MCP (Model Context Protocol) server exposing ISL tools for AI assistants

0High
0Medium
0Low

vibecheckai

isl mcp model-context-protocol ai cursor llm

ISL MCP Server v0.2.0

Model Context Protocol server that exposes ISL tools to AI assistants (Cursor, Claude, custom agents).

The ISL MCP Server brings behavioral verification directly to your AI assistant. Through the Model Context Protocol, AI agents can now run SHIP/NO-SHIP gates, generate code from specifications, and verify implementations against formal intent specifications.

🎯 The SHIP/NO-SHIP Gate

The core value proposition: Every AI-generated code change gets a deterministic gate decision with evidence.

Agent → isl_gate → SHIP (exit 0) + evidence bundle
                 → NO-SHIP (exit 1) + why it failed

Why This Matters

Deterministic - Same inputs always produce the same fingerprint
Auditable - Evidence bundle proves what was verified
CI-native - Exit code gates merge/deploy
Agent-friendly - Any MCP-compatible agent can call it

🛠️ Tool Suite

Core Tools

| Tool | Description | Use Case | |------|-------------|----------| | isl_check | Parse and type-check ISL spec | Validate syntax & types | | isl_generate | Generate TypeScript from spec | Code generation | | isl_constraints | Extract pre/postconditions | Contract analysis | | isl_suggest | Suggest fixes for violations | Auto-healing |

Pipeline Tools (SHIP/NO-SHIP)

| Tool | Description | Criticality | |------|-------------|-------------| | isl_build | Build ISL specs from prompt → code + tests | ⭐ Build phase | | isl_verify | Run verification → collect evidence | ⭐ Verify phase | | isl_gate | SHIP/NO-SHIP decision with evidence bundle | ⭐⭐⭐ Gate decision |

🚀 Quick Start

Installation

# Install globally
npm install -g @isl-lang/mcp-server

# Or install in your project
npm install @isl-lang/mcp-server

Cursor Integration

The server is already configured in .cursor/mcp.json. Just build and use:

cd packages/mcp-server
pnpm build

Claude Desktop Integration

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

{
  "mcpServers": {
    "isl": {
      "command": "node",
      "args": ["path/to/packages/mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

🔄 The Gate Workflow

Complete AI Assistant Workflow

// 1. Agent generates code from intent
const spec = await isl_build({ 
  prompt: "User authentication with rate limiting" 
});

// 2. Verify against spec
const result = await isl_gate({
  spec: specSource,
  implementation: codeSource,
  threshold: 95  // Must score 95%+ to SHIP
});

// 3. Act on decision
if (result.decision === 'SHIP') {
  // Safe to merge - evidence bundle proves it
  console.log(`Trust score: ${result.trustScore}%`);
  console.log(`Evidence: ${result.bundlePath}`);
} else {
  // Block merge - fix the issues first
  console.log(`Blockers: ${result.results.blockers.map(b => b.clause).join(', ')}`);
}

Evidence Bundle Output

When you run isl_gate, it produces a comprehensive evidence bundle:

evidence/
├── manifest.json    # Deterministic fingerprint, input hashes, versions
├── results.json     # Clause-by-clause pass/fail
├── report.html      # Human-readable report
└── artifacts/
    ├── spec.isl       # The spec that was verified
    ├── tests/         # Test results
    └── coverage/      # Coverage metrics

📋 Tool Reference

`isl_gate` ⭐

The core decision maker. Returns SHIP or NO-SHIP with evidence.

Input:

{
  spec: string;           // ISL source or file path
  implementation: string; // Code source or file path
  threshold?: number;     // Min trust score (default: 95)
  writeBundle?: boolean;  // Write evidence to disk (default: true)
  config?: {
    framework?: 'vitest' | 'jest';
    timeout?: number;
    allowSkipped?: boolean;
  }
}

Output:

{
  decision: 'SHIP' | 'NO-SHIP';
  exitCode: 0 | 1;              // For CI
  trustScore: number;           // 0-100
  confidence: number;           // 0-100
  summary: string;              // Human readable
  bundlePath?: string;          // Path to evidence bundle
  manifest?: EvidenceManifest;  // Fingerprint + hashes
  results?: EvidenceResults;    // Clause-by-clause
  suggestion?: string;          // How to fix (if NO-SHIP)
}

`isl_build`

Build specifications from natural language or ISL source.

Input:

{
  prompt: string;         // Natural language or ISL source
  domainName?: string;    // Domain name (default: 'Generated')
  version?: string;       // Version (default: '1.0.0')
  workspacePath?: string; // Output directory
  writeFiles?: boolean;   // Write to disk (default: true)
}

Output:

{
  spec: string;           // Generated ISL specification
  tests: string[];        // Generated test files
  workspace: string;       // Workspace path
  success: boolean;
  errors?: string[];
}

`isl_verify`

Run verification and collect evidence.

Input:

{
  workspacePath?: string;       // Workspace root
  specsPath?: string;           // Path to specs (default: .shipgate/specs)
  implementationPath?: string;  // Path to impl (auto-detected)
  behaviors?: string[];         // Specific behaviors to verify
  framework?: 'vitest' | 'jest';
}

Output:

{
  results: VerificationResult[];
  coverage: CoverageReport;
  violations: Violation[];
  trustScore: number;
  evidence: EvidenceBundle;
}

`isl_check`

Parse and type-check ISL specifications.

Input:

{
  spec: string;           // ISL source or file path
  strict?: boolean;       // Strict mode (default: false)
}

Output:

{
  valid: boolean;
  errors: ValidationError[];
  warnings: ValidationWarning[];
  ast?: ISLNode;          // Abstract syntax tree
}

`isl_generate`

Generate code from ISL specifications.

Input:

{
  spec: string;           // ISL source or file path
  target: 'typescript' | 'python' | 'rust' | 'go';
  output?: string;        // Output directory
  options?: {
    includeTests?: boolean;
    includeDocs?: boolean;
  }
}

Output:

{
  generated: GeneratedFile[];
  success: boolean;
  errors?: string[];
}

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                        MCP Server                           │
├─────────────────────────────────────────────────────────────┤
│  isl_check   │  isl_build   │  isl_verify   │  isl_gate    │
│  (parse)     │  (gen spec)  │  (run tests)  │  (SHIP/NO)   │
├─────────────────────────────────────────────────────────────┤
│                     @isl-lang/parser                        │
│                   @isl-lang/typechecker                     │
│                  @isl-lang/codegen-runtime                  │
│                    @isl-lang/isl-verify                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    evidence/manifest.json
                    evidence/results.json
                    evidence/report.html

🔗 CI/CD Integration

GitHub Actions

name: ISL Gate
on: [push, pull_request]

jobs:
  gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '18'
      
      - name: Install ISL MCP Server
        run: npm install @isl-lang/mcp-server
      
      - name: Run ISL Gate
        run: |
          npx isl-mcp isl_gate \
            --spec ./specs/auth.isl \
            --implementation ./src/auth.ts
        # Exit code 0 = SHIP, 1 = NO-SHIP
      
      - name: Upload Evidence
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: evidence-bundle
          path: evidence/

GitLab CI

isl_gate:
  stage: test
  image: node:18
  script:
    - npm install @isl-lang/mcp-server
    - npx isl-mcp isl_gate --spec specs/ --impl src/
  artifacts:
    reports:
      junit: evidence/results.json
    paths:
      - evidence/
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"

🎛️ Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ISL_MCP_DEBUG | Enable debug logging | false | | ISL_MCP_TIMEOUT | Request timeout (ms) | 30000 | | ISL_MCP_EVIDENCE_DIR | Evidence output directory | ./evidence | | ISL_MCP_STRICT | Strict mode for all tools | false |

Server Configuration

{
  "tools": {
    "isl_gate": {
      "defaultThreshold": 95,
      "writeEvidence": true,
      "framework": "vitest"
    },
    "isl_verify": {
      "timeout": 30000,
      "parallel": true
    }
  },
  "logging": {
    "level": "info",
    "format": "json"
  }
}

📊 Usage Examples

Example 1: Authentication Flow

// Agent prompt: "Add user authentication with rate limiting"
const authSpec = await isl_build({
  prompt: "User authentication with rate limiting",
  domainName: "Auth"
});

// Generate implementation
const authCode = await isl_generate({
  spec: authSpec.spec,
  target: "typescript"
});

// Verify and gate
const result = await isl_gate({
  spec: authSpec.spec,
  implementation: authCode.generated[0].content,
  threshold: 95
});

if (result.decision === 'SHIP') {
  console.log('✅ Authentication flow approved for deployment');
} else {
  console.log('❌ Issues found:', result.results.blockers);
}

Example 2: API Endpoint

// Verify existing implementation
const apiResult = await isl_gate({
  spec: "./specs/payment-api.isl",
  implementation: "./src/payment.ts",
  threshold: 90
});

// Generate evidence badge
if (apiResult.bundlePath) {
  const badge = await isl_proof_badge({
    bundlePath: apiResult.bundlePath,
    format: "svg",
    output: "./badge.svg"
  });
}

🔧 Development

Build from Source

# Clone repository
git clone https://github.com/isl-lang/isl.git
cd isl/packages/mcp-server

# Install dependencies
pnpm install

# Build
pnpm run build

# Run in development
pnpm run dev

Testing

# Run tests
pnpm run test

# Run integration tests
pnpm run test:integration

# Run with coverage
pnpm run test:coverage

Debugging

# Enable debug logging
ISL_MCP_DEBUG=1 pnpm run dev

# Run with specific tool
echo '{"tool": "isl_check", "arguments": {"spec": "test.isl"}}' | \
  node dist/index.js

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for details.

Adding New Tools

Implement tool in src/tools/
Add tool definition in src/index.ts
Write tests in tests/
Update documentation

📚 Resources

ISL Documentation: https://shipgate.dev/docs
MCP Specification: https://modelcontextprotocol.io
GitHub Repository: https://github.com/isl-lang/isl
Discord Community: https://discord.gg/isl
Issues: https://github.com/isl-lang/isl/issues

📄 License

MIT License - see LICENSE file for details.

ISL MCP Server v0.2.0 - Behavioral verification for AI assistants.

"Every AI-generated code change gets a deterministic gate decision with evidence."

Usage

Quick Start (Cursor)

The server is already configured in .cursor/mcp.json. Just build and use:

cd packages/mcp-server
pnpm build

The Gate Workflow

// 1. Agent generates code from intent
const spec = await isl_build({ prompt: "User authentication with rate limiting" });

// 2. Verify against spec
const result = await isl_gate({
  spec: specSource,
  implementation: codeSource,
  threshold: 95  // Must score 95%+ to SHIP
});

// 3. Act on decision
if (result.decision === 'SHIP') {
  // Safe to merge - evidence bundle proves it
  console.log(`Trust score: ${result.trustScore}%`);
  console.log(`Evidence: ${result.bundlePath}`);
} else {
  // Block merge - fix the issues first
  console.log(`Blockers: ${result.results.blockers.map(b => b.clause).join(', ')}`);
}

Evidence Bundle Output

When you run isl_gate, it produces:

evidence/
  manifest.json    # Deterministic fingerprint, input hashes, versions
  results.json     # Clause-by-clause pass/fail
  report.html      # Human-readable report
  artifacts/
    spec.isl       # The spec that was verified

CI Integration

# .github/workflows/verify.yml
- name: ISL Gate
  run: |
    npx isl-mcp isl_gate \
      --spec ./specs/auth.isl \
      --implementation ./src/auth.ts
    # Exit code 0 = SHIP, 1 = NO-SHIP

Tool Reference

`isl_gate`

The core decision maker. Returns SHIP or NO-SHIP with evidence.

Input:

{
  spec: string;           // ISL source or file path
  implementation: string; // Code source or file path
  threshold?: number;     // Min trust score (default: 95)
  writeBundle?: boolean;  // Write evidence to disk (default: true)
  config?: {
    framework?: 'vitest' | 'jest';
    timeout?: number;
    allowSkipped?: boolean;
  }
}

Output:

{
  decision: 'SHIP' | 'NO-SHIP';
  exitCode: 0 | 1;              // For CI
  trustScore: number;           // 0-100
  confidence: number;           // 0-100
  summary: string;              // Human readable
  bundlePath?: string;          // Path to evidence bundle
  manifest?: EvidenceManifest;  // Fingerprint + hashes
  results?: EvidenceResults;    // Clause-by-clause
  suggestion?: string;          // How to fix (if NO-SHIP)
}

`isl_build`

Build specs from natural language or ISL source.

Input:

{
  prompt: string;         // Natural language or ISL source
  domainName?: string;    // Domain name (default: 'Generated')
  version?: string;       // Version (default: '1.0.0')
  workspacePath?: string; // Output directory
  writeFiles?: boolean;   // Write to disk (default: true)
}

`isl_verify`

Run verification and collect evidence.

Input:

{
  workspacePath?: string;       // Workspace root
  specsPath?: string;           // Path to specs (default: .shipgate/specs)
  implementationPath?: string;  // Path to impl (auto-detected)
  behaviors?: string[];         // Specific behaviors to verify
  framework?: 'vitest' | 'jest';
}

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        MCP Server                           │
├─────────────────────────────────────────────────────────────┤
│  isl_check   │  isl_build   │  isl_verify   │  isl_gate    │
│  (parse)     │  (gen spec)  │  (run tests)  │  (SHIP/NO)   │
├─────────────────────────────────────────────────────────────┤
│                     @isl-lang/parser                        │
│                   @isl-lang/typechecker                     │
│                  @isl-lang/codegen-runtime                  │
│                    @isl-lang/isl-verify                     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    evidence/manifest.json
                    evidence/results.json
                    evidence/report.html

Why This Matters

Deterministic - Same inputs always produce same fingerprint
Auditable - Evidence bundle proves what was verified
CI-native - Exit code gates merge/deploy
Agent-friendly - Any MCP-compatible agent can call it

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

ISL MCP Server v0.2.0

🎯 The SHIP/NO-SHIP Gate

Why This Matters

🛠️ Tool Suite

Core Tools

Pipeline Tools (SHIP/NO-SHIP)

🚀 Quick Start

Installation

Cursor Integration

Claude Desktop Integration

🔄 The Gate Workflow

Complete AI Assistant Workflow

Evidence Bundle Output

📋 Tool Reference

isl_gate ⭐

isl_build

isl_verify

isl_check

isl_generate

🏗️ Architecture

🔗 CI/CD Integration

GitHub Actions

GitLab CI

🎛️ Configuration

Environment Variables

Server Configuration

📊 Usage Examples

Example 1: Authentication Flow

Example 2: API Endpoint

🔧 Development

Build from Source

Testing

Debugging

🤝 Contributing

Adding New Tools

📚 Resources

📄 License

Usage

Quick Start (Cursor)

The Gate Workflow

Evidence Bundle Output

CI Integration

Tool Reference

isl_gate

isl_build

isl_verify

Architecture

Why This Matters

License

`isl_gate` ⭐

`isl_build`

`isl_verify`

`isl_check`

`isl_generate`

`isl_gate`

`isl_build`

`isl_verify`