MCP Server Development

• Build commands (mise run catalog:build)
• Test patterns
• Package manager usage (Yarn for catalog)

3. SDK Types (Serena)

Navigate SDK types with Serena:

find_symbol targeting metorial/packages/sdk/

Key types: MCPServer, Tool, Resource, Prompt

Server Structure

Create servers in metorial/servers/<server-name>/:

<server-name>/
├── server.ts          # Main server implementation
├── metorial.json      # Server metadata manifest
├── package.json       # Dependencies
├── tsconfig.json      # TypeScript configuration
└── README.md          # Server documentation

Implementation Workflow

Phase 1: Planning

1. Define server purpose and scope
2. List tools the server will provide
3. Identify external dependencies/APIs
4. Review similar servers with drift_code_examples

Phase 2: Manifest Creation

Create metorial.json:

{
  "name": "server-name",
  "title": "Human Readable Title",
  "description": "What this server does",
  "version": "1.0.0",
  "tools": [
    {
      "name": "tool_name",
      "description": "What the tool does"
    }
  ],
  "configuration": {
    "apiKey": {
      "type": "string",
      "description": "API key for authentication",
      "required": true,
      "env": "SERVICE_API_KEY"
    }
  }
}

Phase 3: Server Implementation

Follow the standard server pattern:

import { MCPServer } from '@metorial/sdk';

const server = new MCPServer({
  name: 'server-name',
  version: '1.0.0',
});

// Define tools
server.tool({
  name: 'tool_name',
  description: 'Tool description',
  inputSchema: {
    type: 'object',
    properties: {
      param: { type: 'string', description: 'Parameter description' }
    },
    required: ['param']
  },
  handler: async (input) => {
    // Implementation
    return { content: [{ type: 'text', text: 'Result' }] };
  }
});

// Start server
server.start();

Phase 4: Validation

1. Build validation:

   mise run catalog:build
   

2. Pattern compliance:

   drift_validate_change
   

3. Local testing:

   bun run dev
   

Best Practices

Error Handling

Follow established error patterns:

try {
  const result = await apiCall();
  return { content: [{ type: 'text', text: JSON.stringify(result) }] };
} catch (error) {
  return {
    content: [{
      type: 'text',
      text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`
    }],
    isError: true
  };
}

Configuration

Use environment variables for sensitive data:

const apiKey = process.env.SERVICE_API_KEY;
if (!apiKey) {
  throw new Error('SERVICE_API_KEY environment variable required');
}

Tool Naming

Follow conventions:

• Use snake_case for tool names
• Prefix with service name for clarity: github_create_issue
• Use descriptive names that indicate action

Input Validation

Validate inputs before processing: