@arial-ai/mcp

A framework for easily building MCP (Model Context Protocol) servers with TypeScript and Node.js.

Features

• Easy server setup with TypeScript support
• Built on top of Express
• Type-safe tool, resource, and prompt definitions
• Automatic session management
• Uses Streamable HTTP (only)

Installation

npm install @arial-ai/mcp
# or
yarn add @arial-ai/mcp
# or
pnpm add @arial-ai/mcp

Quick Start

import { create } from '@arial-ai/mcp';
import { z } from 'zod';

const server = create({
  name: 'my-mcp-server',
  version: '1.0.0',
  port: 3000,
});

// Add a simple echo tool
server.tool(
  'echo-tool',
  'Tool that echoes a message',
  { message: z.string().describe('The message to echo') },
  async ({ message }: { message: string }) => ({
    content: [{ type: 'text', text: `Tool echo: ${message}` }],
  }),
);

// Start the server
server.listen(() => {
  console.log('MCP server is ready!');
});

API Reference

Configuration Options

| Option | Type | Required | Description | | ----------- | -------- | -------- | ---------------------------------------------------- | | name | string | Yes | Name of your MCP server | | version | string | Yes | Version of your server | | port | number | No | Port to run the HTTP server on (default: 3000) | | setupServer | function | No | Optional setup function called during initialization |

Adding Tools

Use the server.tool() method to add new tools to your MCP server:

server.tool(
  'tool-name',
  'Tool description',
  { param: z.string().describe('Parameter description') },
  async ({ param }) => ({
    content: [{ type: 'text', text: `Result: ${param}` }],
  }),
);

Adding Resources

Use the server.resource() method to add resources:

import { ResourceTemplate } from '@arial-ai/mcp';

server.resource(
  'resource-name',
  'Resource description',
  new ResourceTemplate('echo://{message}', { list: undefined }),
  async (uri: any, { message }: { message: string }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Resource content: ${message}`,
      },
    ],
  }),
);

Adding Prompts

Use the server.prompt() method to add prompts:

server.prompt(
  'prompt-name',
  'Prompt description',
  { message: z.string() },
  ({ message }: { message: string }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Please process: ${message}`,
        },
      },
    ],
  }),
);

Complete Example

import { create, ResourceTemplate } from '@arial-ai/mcp';
import { z } from 'zod';

const server = create({
  name: 'example-mcp-server',
  version: '1.0.0',
  port: 3000,
});

// Add a tool
server.tool(
  'calculate',
  'Performs basic arithmetic',
  {
    operation: z.enum(['add', 'subtract', 'multiply', 'divide']),
    a: z.number(),
    b: z.number(),
  },
  async ({ operation, a, b }) => {
    let result;
    switch (operation) {
      case 'add':
        result = a + b;
        break;
      case 'subtract':
        result = a - b;
        break;
      case 'multiply':
        result = a * b;
        break;
      case 'divide':
        result = a / b;
        break;
    }
    return {
      content: [{ type: 'text', text: `${a} ${operation} ${b} = ${result}` }],
    };
  },
);

// Add a resource
server.resource(
  'status',
  'Server status information',
  new ResourceTemplate('status://{type}', { list: undefined }),
  async (uri, { type }) => ({
    contents: [
      {
        uri: uri.href,
        text: `Server status (${type}): Running`,
      },
    ],
  }),
);

// Add a prompt
server.prompt(
  'greeting',
  'Generate a greeting message',
  { name: z.string() },
  ({ name }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Generate a friendly greeting for ${name}`,
        },
      },
    ],
  }),
);

server.listen(() => {
  console.log('Server ready on port 3000');
});

Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Start development server:

   npm run dev

Building

npm run build

License

MIT