Example MCP Server

A simple example MCP (Model Context Protocol) server built with TypeScript that demonstrates basic functionality including tools and resources. This server can be used as a learning example or starting point for building your own MCP servers.

Features

This example MCP server provides:

• 5 Example Tools:

  • add - Add two numbers together
  • multiply - Multiply two numbers together
  • get_random_quote - Generate a random inspirational quote
  • reverse_string - Reverse a given string
  • fibonacci - Calculate the nth Fibonacci number

• 2 Example Resources:

  • greeting - A simple greeting message
  • server_info - Information about the server and its capabilities

Installation and Usage

Quick Start with npx

You can run this MCP server directly without installation:

npx @teodortrotea/teodor-mcp-server

Global Installation

npm install -g teodor-mcp-server
teodor-mcp-server

Local Development

1. Clone/download this example
2. Install dependencies:

   npm install

3. Build the project:

   npm run build

4. Run the server:

   npm start

Using with MCP Clients

This server is designed to work with any MCP client using the standard configuration format. Simply add it to your client's MCP server configuration.

Universal MCP Client Configuration

Use this configuration in any MCP client (Claude Desktop, Cursor, or custom implementations):

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": [
        "-y",
        "teodor-mcp-server"
      ],
      "env": {}
    }
  }
}

Claude Desktop

Windows: %APPDATA%/Claude/claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "teodor-mcp-server"]
    }
  }
}

Cursor IDE

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "teodor-mcp-server"],
      "env": {}
    }
  }
}

Continue.dev

Add to your Continue configuration:

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "teodor-mcp-server"]
    }
  }
}

Custom MCP Clients

For any custom MCP client implementation, use the standard stdio transport with:

• Command: npx
• Arguments: ["-y", "teodor-mcp-server"]
• Transport: stdio (stdin/stdout)
• Protocol: MCP 1.0

Configuration Options

The -y flag ensures automatic package installation without prompts, which is recommended for client configurations.

You can also specify environment variables if needed:

{
  "mcpServers": {
    "example-server": {
      "command": "npx",
      "args": ["-y", "teodor-mcp-server"],
      "env": {
        "NODE_ENV": "production",
        "DEBUG": "false"
      }
    }
  }
}

Example Tool Usage

Once connected to an MCP client, you can use the tools like this:

Addition Tool

• Name: add
• Parameters: a (number), b (number)
• Example: Add 5 and 3 to get 8

Multiplication Tool

• Name: multiply
• Parameters: a (number), b (number)
• Example: Multiply 4 and 7 to get 28

Random Quote Generator

• Name: get_random_quote
• Parameters: None
• Example: Get a random inspirational quote

String Reverser

• Name: reverse_string
• Parameters: text (string)
• Example: Reverse "hello world" to get "dlrow olleh"

Fibonacci Calculator

• Name: fibonacci
• Parameters: n (number, >= 0)
• Example: Calculate the 10th Fibonacci number

Example Resources

Greeting Resource

• URI: greeting://example
• Type: Plain text
• Description: A simple welcome message

Server Info Resource

• URI: info://server
• Type: JSON
• Description: Detailed information about the server's capabilities

Development

Project Structure

teodor-mcp-server/
├── src/
│   └── index.ts          # Main server implementation
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Building Your Own MCP Server

This example demonstrates the key concepts for building MCP servers:

1. Server Setup: Create an McpServer instance with name and version
2. Tool Registration: Use server.registerTool() to add executable functions
3. Resource Registration: Use server.registerResource() to add data endpoints
4. Transport: Use StdioServerTransport for communication
5. Schema Validation: Use Zod schemas for input validation

Key Code Patterns

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "your-server-name",
  version: "1.0.0"
});

// Register a tool
server.registerTool("tool_name", {
  title: "Tool Title",
  description: "What this tool does",
  inputSchema: {
    param1: z.string().describe("Parameter description"),
    param2: z.number().describe("Another parameter")
  }
}, async ({ param1, param2 }) => {
  // Tool implementation
  return {
    content: [{ type: "text", text: "Result" }]
  };
});

// Register a resource
server.registerResource("resource_name", "uri://path", {
  title: "Resource Title",
  description: "What this resource provides",
  mimeType: "text/plain"
}, async (uri) => {
  return {
    contents: [{
      uri: uri.href,
      mimeType: "text/plain",
      text: "Resource content"
    }]
  };
});

// Start the server
const transport = new StdioServerTransport();
await server.connect(transport);

Requirements

• Node.js 18.x or higher
• TypeScript 5.x (for development)

Dependencies

• @modelcontextprotocol/sdk - Official MCP TypeScript SDK
• zod - Schema validation library

License

MIT

Contributing

This is an example project. Feel free to use it as a starting point for your own MCP servers or suggest improvements!

Troubleshooting

Common Issues

1. "Module not found" errors: Ensure you've run npm install and npm run build
2. Permission denied: Make sure the compiled JavaScript file is executable (chmod +x dist/index.js)
3. Connection issues: Verify your MCP client configuration matches the command format

Debug Mode

To see debug output from the server:

NODE_ENV=development npx @teodortrotea/teodor-mcp-server

Learn More

• Model Context Protocol Documentation
• MCP TypeScript SDK
• MCP Specification

What's Next?

Try extending this example by:

• Adding more complex tools with external API calls
• Implementing dynamic resources with parameters
• Adding prompt templates
• Integrating with databases or file systems
• Building web scrapers or data processors