Simply MCP

Type-safe TypeScript framework for building MCP servers with pure interface-driven API - zero boilerplate, full type safety.

What is Simply MCP?

Simply MCP is a TypeScript framework that makes building Model Context Protocol (MCP) servers effortless. Instead of writing verbose schema definitions and boilerplate code, you define your server's capabilities using pure TypeScript interfaces—and Simply MCP handles the rest.

The Problem: Traditional MCP server development requires manual schema definitions, protocol handling, and extensive boilerplate code.

The Solution: Simply MCP uses AST-based extraction to automatically generate all protocol schemas from your TypeScript interfaces, giving you full type safety with zero boilerplate.

Built on top of the official Anthropic MCP SDK, Simply MCP adds developer experience features like hot reload, React UI support, tool routing, and OAuth 2.1 authentication—all configured through TypeScript interfaces.

Key Features

✨ Zero-Boilerplate API Define tools, resources, and prompts using pure TypeScript interfaces. Full IntelliSense, compile-time validation, and automatic schema generation.

🚀 Multiple Transport Modes Stdio, HTTP (stateful with sessions/SSE), and HTTP (stateless for serverless). Built-in API key and OAuth 2.1 authentication.

🔌 Complete MCP Protocol Support Sampling, elicitation, roots, subscriptions, progress messages, tool annotations, JSON-RPC batch processing, and autocomplete.

🎨 React UI Resources Build interactive UIs with React/JSX, automatic bundling, hot reload, and adapter hooks for any component library (shadcn, Radix, Material-UI).

🎵 Rich Content Types Serve audio resources (MP3, WAV, OGG, FLAC) with metadata, text/image/embedded content, and dynamic resources.

Learn More: Complete Feature List

Quick Start

Installation

npm install simply-mcp

Optional Dependencies: Simply-MCP uses lazy loading for advanced features. Dependencies are only required when you use them:

• HTTP transport → express, cors
• Watch mode → chokidar
• Bundling → esbuild
• Minification → terser, html-minifier-terser, cssnano
• Client rendering → @remote-dom/core, @remote-dom/react, react, react-dom

Create Your First Server

Simply MCP supports two API patterns: const-based (simpler, functional) and class-based (traditional). Both are fully supported.

Const Pattern (Recommended for new projects):

// server.ts
import type { ITool, IParam, IServer, ToolHelper } from 'simply-mcp';

// 1. Configure your server
const server: IServer = {
  name: 'my-server',
  version: '1.0.0',
  description: 'A helpful MCP server'
};

// 2. Define parameter interface
interface NameParam extends IParam {
  type: 'string';
  description: 'Person name to greet';
}

// 3. Define your tool interface
interface GreetTool extends ITool {
  name: 'greet';
  description: 'Greet someone';
  params: { name: NameParam };
  result: string;
}

// 4. Implement tool as const
const greet: ToolHelper<GreetTool> = async (params) => `Hello, ${params.name}!`;

// 5. Export implementations
export { server, greet };

Class Pattern (Alternative - same interfaces):

// 4. Implement the server as class
export default class Server {
  greet: ToolHelper<GreetTool> = async (params) => `Hello, ${params.name}!`;
}

Why const pattern?

• Less boilerplate (no class declaration)
• Simpler syntax (direct assignments)
• Functional programming style
• Better type inference

When to use class?

• Need shared state (this.counter, this.db)
• Complex initialization logic
• Multiple tools sharing data

See Const Patterns Guide for complete reference.

Advanced Parameter Types

Simply MCP supports complex TypeScript types with automatic schema generation:

Nested Objects:

interface CreateUserTool extends ITool {
  name: 'create_user';
  params: {
    user: {
      name: string;
      email: string;
      address: {
        street: string;
        city: string;
        zipCode?: string;  // Optional nested field
      };
    };
  };
}

Typed Arrays:

interface ProcessItemsTool extends ITool {
  name: 'process_items';
  params: {
    tags: string[];           // String array
    scores: number[];         // Number array
    items: Array<{            // Array of objects
      id: string;
      value: number;
    }>;
  };
}

Union Types (Enums):

interface SetStatusTool extends ITool {
  name: 'set_status';
  params: {
    status: 'active' | 'inactive' | 'pending';  // Automatically becomes enum
  };
}

JSDoc Descriptions:

interface MyTool extends ITool {
  name: 'my_tool';
  params: {
    /** User's full name */
    name: string;
    /** User's age in years */
    age: number;
  };
}

All these patterns work with strict type validation and automatic schema generation during bundling.

Choosing Your Pattern: ToolHelper vs Bare Interface

Simply-MCP supports two equally valid patterns for implementing tools, prompts, and resources:

| Pattern | Best For | Type Safety | TypeScript Strictness | |---------|----------|-------------|----------------------| | ToolHelper | Maximum type safety, complex params | Full inference | Works with strict: true | | Bare Interface | Simple tools, quick prototypes | Manual typing | Requires strict: false |

When to use ToolHelper?

✅ Use ToolHelper<T> when:

• You encounter TypeScript errors with bare interface pattern
• Complex parameter types with nested objects
• Need automatic type inference for params and return types
• Team prefers explicit typing
• Working in strict TypeScript mode

const greet: ToolHelper<GreetTool> = async (params) => {
  return `Hello, ${params.name}!`;  // ✅ params.name typed automatically
};

When to use bare interface?

✅ Use bare interface when:

• Simple tools with basic params (strings, numbers, booleans)
• Quick prototypes or examples
• Familiar with manual typing
• Minimal boilerplate preferred
• Working in relaxed TypeScript mode

const greet: GreetTool = async (params) => {
  return `Hello, ${params.name}!`;  // ⚠️ params type must match manually
};

Troubleshooting: If you get TypeScript errors like "Type 'X' is not assignable to type 'Y'", use the ToolHelper pattern for automatic type inference. See Const Patterns Guide for detailed troubleshooting.

Validate Your Server

npx simply-mcp run server.ts --dry-run

The dry-run validates your interface definitions and catches configuration errors early.

Run Your Server

# STDIO transport (default - recommended for Claude CLI)
npx simply-mcp run server.ts

# HTTP transport (stateful with sessions + SSE)
npx simply-mcp run server.ts --transport http --port 3000

# HTTP transport (stateless for serverless/AWS Lambda)
npx simply-mcp run server.ts --transport http-stateless --port 3000

# WebSocket transport (real-time bidirectional communication)
npx simply-mcp run server.ts --transport ws --port 8080

# Legacy flags (backward compatible)
npx simply-mcp run server.ts --http --port 3000
npx simply-mcp run server.ts --http-stateless --port 3000

That's it! Your MCP server is running with full type safety and zero boilerplate.

Next Steps:

• 📘 Quick Start Guide - Detailed tutorial with testing & troubleshooting
• 📘 Features Guide - Tools, prompts, resources
• 📘 API Reference - Complete API documentation

Using with Claude CLI

Simply MCP servers integrate seamlessly with Anthropic's Claude CLI using stdio transport. This allows you to use your MCP tools directly in Claude conversations.

Quick Setup

1. Bundle Your Server (recommended for best startup time):

npx simply-mcp bundle src/my-server.ts -o dist/my-server.js

2. Create MCP Configuration File:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": [
        "node_modules/simply-mcp/dist/src/cli/index.js",
        "run",
        "dist/my-server.js"
      ],
      "env": {
        "MCP_TIMEOUT": "30000"
      }
    }
  }
}

Save this as mcp-config.json in your project root.

3. Run Claude CLI with Your Server:

# Set timeout environment variable
export MCP_TIMEOUT=30000

# Use Claude with your MCP server
claude --mcp-config mcp-config.json "Use my-server to help me"

Important Configuration Notes

Timeout Configuration: Simply MCP servers take approximately 2 seconds to start up. The default MCP timeout is too short, so you must set MCP_TIMEOUT=30000 (30 seconds) either:

• As an environment variable: export MCP_TIMEOUT=30000
• In the env section of your MCP config (as shown above)
• Inline with your command: MCP_TIMEOUT=30000 claude --mcp-config config.json "prompt"

Bundling vs Direct TypeScript: We strongly recommend bundling your server for production use with Claude CLI:

• ✅ Bundled (dist/my-server.js): Fast startup, reliable, recommended
• ⚠️ TypeScript (src/my-server.ts): Currently has loader issues, use bundled instead

Testing Your Setup

Validate your configuration with a simple test:

# Test that your server starts correctly
node node_modules/simply-mcp/dist/src/cli/index.js run dist/my-server.js --dry-run

# Test with Claude CLI (non-interactive)
MCP_TIMEOUT=30000 claude --print \
  --model haiku \
  --mcp-config mcp-config.json \
  --strict-mcp-config \
  --dangerously-skip-permissions \
  "List available tools from my-server"

Troubleshooting

"Connection timeout" or "Failed to connect to server"

• Increase timeout: export MCP_TIMEOUT=30000 or add to config env section
• Verify server starts manually: node ... run dist/my-server.js --dry-run

"Cannot find module" errors

• Use bundled servers (dist/my-server.js) instead of TypeScript sources
• Ensure bundle exists: ls dist/my-server.js

Tools not appearing

• Check server validation: npx simply-mcp run dist/my-server.js --dry-run
• Verify MCP config syntax is valid JSON
• Try with --strict-mcp-config flag to isolate server issues

HTTP transport "Cannot POST /" or "Not Acceptable" errors

• stdio transport is recommended for Claude CLI (HTTP has additional configuration requirements)
• If using HTTP: endpoint is /mcp, not /
• Required header: Accept: application/json, text/event-stream

See the Quick Start Guide for more detailed troubleshooting.

Progressive Disclosure with AI Skills

New in v4.4.0 - Reduce token usage by 60-67% through intelligent capability hiding

Progressive disclosure allows you to hide MCP capabilities from initial discovery while making them accessible through AI Skills. This dramatically reduces token usage in the discovery phase while preserving full functionality.

Key Benefits:

• 60-67% token reduction in initial discovery
• Context-aware hiding based on user roles, permissions, or feature flags
• Auto-generated documentation for hidden capabilities
• Compile-time validation catches configuration issues early
• 100% backward compatible

Quick Example

import { ITool, ISkill, HiddenEvaluationContext } from 'simply-mcp';

// Public tool (visible to everyone)
interface SearchTool extends ITool {
  name: 'search';
  description: 'Search public data';
  params: { query: string };
  result: { results: string[] };
  // No hidden flag = visible by default
}

// Hidden tool (static - always hidden)
interface DebugTool extends ITool {
  name: 'debug';
  description: 'Debug internal state';
  params: { component: string };
  result: { state: any };
  hidden: true;  // Always hidden from tools/list
}

// Dynamic hidden tool (context-aware)
interface AdminTool extends ITool {
  name: 'reset';
  description: 'Reset server state';
  params: { confirm: boolean };
  result: { success: boolean };
  hidden: (ctx?: HiddenEvaluationContext) => {
    const user = ctx?.metadata?.user as { role?: string } | undefined;
    return user?.role !== 'admin';  // Hide if not admin
  };
}

// Auto-generated skill (documents hidden tools)
interface DebugSkill extends ISkill {
  name: 'debug_toolkit';
  description: 'Debug and diagnostic tools';
  tools: ['debug'];  // Auto-generates documentation from flat array
}

Discovery Flow:

# 1. Initial discovery (anonymous user)
List all tools → [search]  # Only public tool visible (300 tokens)

# 2. Discover hidden capabilities via skill
Get the debug_toolkit skill → Returns auto-generated docs for debug tool

# 3. Call hidden tool directly
Call debug({ component: 'cache' }) → { state: {...} }

Token Reduction:

• Before: All 50 tools exposed = 5000 tokens
• After: 10 public + 40 hidden = 1700 tokens (66% reduction)

Features

Foundation Layer:

• ✅ Static hidden flag for tools, resources, and prompts
• ✅ Manual skills with handcrafted documentation
• ✅ Basic progressive disclosure workflow

Feature Layer:

• ✅ Dynamic hidden evaluation (runtime context-based)
• ✅ Auto-generated skill documentation (zero maintenance)
• ✅ Compile-time validation (catches orphaned hidden items)

Common Use Cases

Role-Based Access Control:

hidden: (ctx) => {
  const user = ctx?.metadata?.user as { role?: string } | undefined;
  return user?.role !== 'admin';
}

Feature Flags:

hidden: (ctx) => {
  const flags = ctx?.metadata?.feature_flags as string[] | undefined;
  return !flags?.includes('experimental_feature');
}

Hide Debug Tools:

interface DebugTool extends ITool {
  name: 'debug';
  hidden: true;  // Always hidden (debug/internal use only)
}

Learn More:

• 📘 Progressive Disclosure Guide - Complete feature documentation
• 📘 Migration Guide - Upgrade from v4.3.x
• 📘 ISkill API Reference - Interface reference
• 💡 Examples - Auth-gated and feature flag examples

Transport & Authentication

Simply MCP supports multiple transports and authentication methods configured via interfaces:

Transport Options:

• Stdio - Standard input/output (default, best for Claude CLI)
• HTTP Stateful - Sessions + Server-Sent Events (SSE)
• HTTP Stateless - Serverless-ready (AWS Lambda, Vercel)
• WebSocket - Real-time bidirectional communication

Authentication:

• API Key - Simple key-based auth for internal tools
• OAuth 2.1 - Authorization Code + PKCE flow with scope-based access control

All configuration is type-safe and declared in your IServer interface.

Learn More: Transport Guide | OAuth 2.1 Guide | API Reference

UI Adapter Layer - React Hooks

Build UIs with any React component library using hooks that eliminate boilerplate:

const search = useMCPTool('search_products', {
  onSuccess: (data) => console.log('Found:', data)
});

return <Button onClick={() => search.execute({ query: 'laptop' })}
               disabled={search.loading}>
  {search.loading ? 'Searching...' : 'Search'}
</Button>

Available Hooks: useMCPTool, usePromptSubmit, useIntent, useNotify, useOpenLink

Works with: shadcn/ui, Radix UI, Material-UI, Chakra UI, native HTML

Learn More: MCP UI Adapter Hooks Guide | Examples

Tool Routers

Organize related tools into namespaced groups to reduce context clutter:

interface WeatherRouter extends IToolRouter {
  name: 'weather_router';
  description: 'Weather information tools';
  tools: [GetWeatherTool, GetForecastTool];
}

When flattenRouters: false, only the router appears in the main tools list. Call the router to discover available tools, then access them via namespace: weather_router__get_weather

Learn More: Router Tools Guide

Batch Processing

Process multiple tool calls efficiently with JSON-RPC 2.0 batch support:

const server = new BuildMCPServer({
  batching: {
    enabled: true,
    parallel: true,      // 5x faster throughput
    maxBatchSize: 100    // DoS protection
  }
});

Performance: 940 requests/second (parallel) vs 192 requests/second (sequential). Tools receive batch context for resource pooling optimization.

Learn More: Batch Processing Guide

Documentation

📚 Getting Started

• Quick Start - Get started in 5 minutes
• Features Guide - Complete feature reference
• API Reference - Full API documentation

🔧 Core Features

• Transport Guide - Stdio, HTTP stateful/stateless
• Authentication - OAuth 2.1 and API keys
• Validation Guide - Parameter validation
• Router Tools - Namespaced tool organization

🎨 UI Resources

• MCP UI Protocol - UI protocol reference
• MCP UI Adapter Hooks - React hooks API
• Remote DOM Advanced - Performance tuning
• Remote DOM Troubleshooting - Debug guide

⚡ Advanced Topics

• Protocol Features - Sampling, elicitation, subscriptions
• Batch Processing - High-throughput optimization
• Configuration - Environment variables
• Bundling - Production deployment

Examples

Getting Started:

• bundle-test-server.ts - Minimal interface-driven server (great starting point)
• const-patterns/minimal-server.ts - Complete const-based API patterns
• const-patterns/all-primitives.ts - All 10 MCP primitives as const

Transport Examples:

• interface-websocket.ts - WebSocket transport with real-time communication
• OAuth Examples - See examples/oauth-*.ts for in-memory, Redis, router, and scope enforcement patterns

UI Examples:

• v4/01-minimal.ts - Inline HTML UI
• v4/03-react-component.ts - React with JSX
• v4/06-remote-dom.ts - Shopify Remote DOM integration
• v4/07-with-tools.ts - UI + tools combined
• ui-with-hooks/ - MCP UI adapter hooks with component libraries

Code Execution:

• v4/code-execution-server.ts - Secure code execution with isolated-vm
• v4/code-execution-docker-server.ts - Docker-based isolation

Production Bundles:

• calculator-bundle/ - Complete bundled server with arithmetic operations
• weather-bundle/ - Weather services with forecasts and alerts

Troubleshooting:

• troubleshooting/pattern-migration.ts - Migration guide
• troubleshooting/typescript-errors.ts - Common errors and solutions

MCP Interpreter - Reference Client

A Next.js application demonstrating MCP client integration with visual interfaces for testing and development.

Features:

• Visual interface for all MCP primitives (tools, resources, prompts, roots, sampling, elicitation)
• Connection management for testing MCP servers
• Sandboxed iframe support for UI resources with postMessage communication
• Implementation of MCP UI adapter hooks

Location: inspector/

Use Cases:

• Testing your MCP servers during development
• Learning how to build MCP clients
• Reference implementation for client-side MCP integration

Testing

# Run all tests
npm test

# Run unit tests
npm run test:unit

# Run with coverage
npm run test:unit:coverage

CI/CD Pipeline:

• ✅ Unit tests + Examples validation: Required (blocks PRs on failure)
• ⚠️ Integration tests: Informational (non-blocking)

Pre-Release Testing

Before releasing a new version, run manual tests with Claude CLI to catch regressions:

# Build the project
npm run build

# Run manual tests (requires Claude CLI installed)
bash tests/manual/test-bundled-schemas-with-claude-cli.sh

These tests verify:

• Bundled servers generate proper parameter schemas
• Parameter validation works with real MCP clients
• Both stdio and HTTP transports function correctly

See tests/manual/README.md for details.

Development

Getting Started with Development

# Clone the repo
git clone https://github.com/Clockwork-Innovations/simply-mcp-ts.git
cd simply-mcp-ts

# Install dependencies
npm install

# Build
npm run build

# Run examples
npx simply-mcp run examples/interface-minimal.ts

Development Workflow

# Watch mode for development
npm run dev

# Test your changes
npm run test:unit
npm run test:examples

# Run full test suite
npm test

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT © Nicholas Marinkovich, MD

Links

• NPM Package
• GitHub Repository
• Issue Tracker
• Changelog

Support

• 📖 Documentation
• 💬 Discussions
• 🐛 Issue Tracker

Acknowledgments

Built with the Model Context Protocol SDK by Anthropic.