Elysia MCP Plugin

⚠️ Under Development

A comprehensive ElysiaJS plugin for implementing
Model Context Protocol (MCP) servers
with HTTP transport support.

Features

HTTP Transport: Full HTTP-based MCP transport with Streamable HTTP
Session Management: Stateful session handling via headers
Type-Safe: Built with TypeScript and Zod validation
Easy Integration: Simple plugin architecture for Elysia apps
Comprehensive Support: Tools, Resources, Prompts, and Logging
Error Handling: Proper JSON-RPC 2.0 error responses
Testing: Full unit test coverage with Bun test runner

Installation

bun add elysia-mcp
# or
npm install elysia-mcp

Starter Template

To quickly get started with a pre-configured Elysia MCP project, you can use our starter template:

# Create a new project from the starter template
bun create https://github.com/kerlos/elysia-mcp-starter my-mcp-project

# Navigate to the project
cd my-mcp-project

# Install dependencies
bun install

# Start development server
bun run dev

The elysia-mcp-starter template includes:

Pre-configured Elysia setup with MCP plugin
TypeScript configuration
Development scripts
Basic project structure
Example MCP server implementation

Quick Start

import { Elysia } from 'elysia';
import { mcp } from 'elysia-mcp';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const app = new Elysia()
  .use(
    mcp({
      serverInfo: {
        name: 'my-mcp-server',
        version: '1.0.0',
      },
      capabilities: {
        tools: {},
        resources: {},
        prompts: {},
        logging: {},
      },
      setupServer: async (server: McpServer) => {
        // Register your MCP tools, resources, and prompts here
        server.tool(
          'echo',
          {
            text: z.string().describe('Text to echo back'),
          },
          async (args) => {
            return {
              content: [{ type: 'text', text: `Echo: ${args.text}` }],
            };
          }
        );
      },
    })
  )
  .listen(3000);

Usage

Running the Examples

Basic Example:

# Run the basic example server (port 3000)
bun run example

# Or with development mode (auto-restart)
bun run dev

Multiple Servers Example:

# Run the multiple MCP servers example (port 3000)
bun example:multi

This example demonstrates how to create multiple MCP plugins in a single Elysia application:

Math Operations Plugin (/math) - Basic arithmetic tools:
- add - Add two numbers
- multiply - Multiply two numbers
- power - Calculate base to the power of exponent
Text Utilities Plugin (/text) - Text processing tools:
- uppercase - Convert text to uppercase
- word_count - Count words in text
- reverse - Reverse text characters
- replace - Replace text with global matching

Testing with MCP Inspector

Install MCP Inspector:
```
npx @modelcontextprotocol/inspector
```
Connect to your server:
- Basic Example: http://localhost:3000/mcp
- Multiple Servers Example:
  - Math Plugin: http://localhost:3000/math
  - Text Plugin: http://localhost:3000/text

Configuration Options

serverInfo: Server information
capabilities: MCP capabilities to advertise
enableLogging: Enable debug logging (default: false)
setupServer: Callback to register tools, resources, and prompts

Session Management

The plugin automatically handles session management via the Mcp-Session-Id
header. Each session maintains its own state and can be terminated cleanly.

Modular Handler Architecture

The plugin supports a modular handler architecture that allows you to create specialized endpoints for different MCP capabilities:

import {
  mcp,
  ToolsHandler,
  ResourcesHandler,
  PromptsHandler,
} from 'elysia-mcp';

const app = new Elysia().use(
  mcp({
    /* config */
  })
);

API Reference

Tools

server.tool(
  'tool-name',
  {
    param: z.string().describe('Parameter description'),
  },
  async (args) => {
    // Tool implementation
    return {
      content: [{ type: 'text', text: 'Tool result' }],
    };
  }
);

Resources

server.resource('Resource Name', 'resource://uri', async () => {
  return {
    contents: [
      {
        uri: 'resource://uri',
        mimeType: 'text/plain',
        text: 'Resource content',
      },
    ],
  };
});

Prompts

server.prompt(
  'prompt-name',
  'Prompt description',
  {
    param: z.string().describe('Parameter description'),
  },
  async (args) => {
    return {
      description: 'Generated prompt',
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Generated prompt with ${args.param}`,
          },
        },
      ],
    };
  }
);

Testing

Run the comprehensive test suite:

bun test

License

MIT - see LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Plugin Configuration

Plugin Options

interface MCPPluginOptions {
  serverInfo?: {
    name: string;
    version: string;
  };
  capabilities?: ServerCapabilities;
  enableLogging?: boolean;
  setupServer?: (server: McpServer) => void | Promise<void>;
}

Architecture

┌─────────────────┐    ┌──────────────┐    ┌─────────────────┐
│   HTTP Client   │───▶│ Elysia HTTP  │───▶│    MCP Plugin   │
│                 │    │   Handler    │    │                 │
└─────────────────┘    └──────────────┘    └─────────────────┘
                                                     │
                                                     │
                                            ┌─────────────────┐
                                            │    McpServer    │
                                            │   (Singleton)   │
                                            └─────────────────┘

Elysia Mcp

Overview

What is Elysia Mcp

Use cases

How to use

Key features

Where to use

Content