Package Exports

mcp-conductor
mcp-conductor/src/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (mcp-conductor) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

MCP Conductor

A comprehensive Node.js testing

Documentation

📚 Complete Documentation

🚀 Installation
⚡ Quick Start Guide
📝 YAML Testing
💻 Programmatic Testing
🔍 Pattern Matching
🏗️ Examples
🛠️ API Reference
🔧 TroubleshootingModel Context Protocol (MCP) servers

MCP Conductor provides both YAML-based declarative testing and programmatic testing for MCP servers with advanced pattern matching capabilities.

⚡ Quick Start

# Install globally
npm install -g mcp-conductor

# Initialize in your MCP project
npx mcp-conductor init

# The init command creates:
# - conductor.config.json (configured from package.json)
# - test/mcp/ or tests/mcp/ directory (based on existing project structure)
# - AGENTS.md (AI agent guide) in the test directory
# - Installs mcp-conductor as a dev dependency

# Customize your config (optional)
# Edit conductor.config.json to match your server setup

# Write your first test
cat > tests/mcp/my-server.test.mcp.yml << 'EOF'  # or test/mcp/ depending on your project
description: "Basic test"
tests:
  - it: "should list tools"
    request:
      jsonrpc: "2.0"
      id: "1"
      method: "tools/list"
      params: {}
    expect:
      response:
        jsonrpc: "2.0"
        id: "1"
        result:
          tools: "match:type:array"
EOF

# Run tests (after init, you can use npx or npm script)
npx mcp-conductor "test*/mcp/**/*.test.mcp.yml"  # Matches both test/ and tests/

# Or add to package.json scripts:
# "scripts": { "test:mcp": "mcp-conductor \"./test*/mcp/**/*.test.mcp.yml\"" }
# Then run: npm run test:mcp

Manual Setup (Alternative)

# Create config manually
echo '{"name":"My Server","command":"node","args":["./server.js"]}' > conductor.config.json

# Write test
cat > test.yml << 'EOF'
description: "Basic test"
tests:
  - it: "should list tools"
    request:
      jsonrpc: "2.0"
      id: "1"
      method: "tools/list"
      params: {}
    expect:
      response:
        jsonrpc: "2.0"
        id: "1"
        result:
          tools: "match:type:array"
EOF

# Run test
conductor test.yml --config conductor.config.json

✨ Key Features

🎯 Declarative YAML Testing - Simple, readable test definitions
💻 Programmatic API - JavaScript/TypeScript integration with any test framework
🔄 Automatic MCP Protocol - Handles handshakes and JSON-RPC messaging
🧪 Advanced Pattern Matching - 11+ verified pattern types with robust validation
📊 Rich Reporting - Detailed diffs and colored output
🛡️ Robust Communication - Reliable stdio transport handling

📖 Documentation

📚 Complete Documentation

🚀 Testing Approaches

YAML Declarative Testing

description: "Calculator tests"
tests:
  - it: "should add numbers"
    request:
      jsonrpc: "2.0"
      id: "calc-1"
      method: "tools/call"
      params:
        name: "calculator"
        arguments: { a: 15, b: 27 }
    expect:
      response:
        jsonrpc: "2.0"
        id: "calc-1"
        result:
          content:
            - type: "text"
              text: "match:Result: \\d+"

Programmatic Testing

import { test, before, after } from 'node:test';
import { connect } from 'mcp-conductor';

let client;
before(async () => { client = await connect('./config.json'); });
after(async () => { await client.disconnect(); });

test('calculator adds correctly', async () => {
  const result = await client.callTool('calculator', { a: 15, b: 27 });
  assert.equal(result.content[0].text, 'Result: 42');
});

🏃‍♂️ Running Tests

# YAML tests
conductor "tests/**/*.test.mcp.yml" --config config.json

# Programmatic tests  
node --test tests/**/*.programmatic.test.js

# Example tests (included)
npm run test:examples

🤝 Contributing

Contributions welcome! See our Contributing Guide for details.

# Development setup
git clone https://github.com/taurgis/mcp-conductor.git
cd mcp-conductor
npm install

# Run all tests
npm test

📜 License

MIT License - see LICENSE file for details.

📚 View Complete Documentation | 🐛 Report Issues | ⭐ Star on GitHub