MCP by VimeansethThorng - MCP Server

Example MCP Server

A complete Model Context Protocol (MCP) server available in both TypeScript and Python implementations, demonstrating all core MCP capabilities including resources, tools, and prompts.

Project Structure

MCP/
├── typescript-server/          # TypeScript implementation
│   ├── src/
│   │   └── index.ts           # Main TypeScript server
│   ├── build/                 # Compiled JavaScript
│   ├── package.json           # Node.js dependencies
│   ├── tsconfig.json          # TypeScript config
│   └── README.md              # TypeScript-specific docs
├── python-server/             # Python implementation
│   ├── src/
│   │   ├── __init__.py        # Package initialization
│   │   └── server.py          # Main Python server
│   ├── .venv/                 # Virtual environment
│   ├── requirements.txt       # Python dependencies
│   ├── pyproject.toml         # Python packaging
│   ├── setup.py               # Python setup script
│   ├── test_server.py         # Python tests
│   ├── PYTHON_SERVER.md       # Python-specific docs
│   ├── MYSQL_TOOL.md          # MySQL tool documentation
│   └── README.md              # Python-specific docs
├── docs/                      # Project documentation
│   ├── MIGRATION_SUMMARY.md   # Migration notes
│   ├── PROJECT_STRUCTURE.md   # Structure details
│   └── REORGANIZATION_SUMMARY.md # Reorganization notes
├── .vscode/
│   └── mcp.json               # VS Code MCP configuration
├── .github/                   # GitHub configuration
├── test-servers.sh            # Test script for both servers
└── README.md                  # This file

Implementations

🟦 TypeScript Version

Built with Node.js and TypeScript
Uses the MCP TypeScript SDK
Located in typescript-server/

🐍 Python Version

Built with Python 3.8+
Uses the MCP Python SDK
Located in python-server/

Both implementations provide identical functionality and can be used interchangeably.

Features

This MCP server provides:

📄 Resources

Static README: Access to project documentation
Dynamic User Profiles: Parameterized user information resources

🔧 Tools

Calculator: Perform basic mathematical operations (add, subtract, multiply, divide)
System Information: Get current time, platform details, and memory usage
Data Generator: Create mock data for testing (users, products, orders)
MySQL Query: Execute SELECT queries against MySQL databases safely

📝 Prompts

Concept Explanation: Generate detailed explanations for technical concepts
Code Review: Perform comprehensive code reviews with customizable focus areas
Project Planning: Assist with project planning and structure

Quick Start

Prerequisites

For TypeScript:

Node.js v18.x or higher
npm or yarn

For Python:

Python 3.8 or higher
pip

Installation

TypeScript Setup:

Navigate to TypeScript server:
```
cd typescript-server
```
Install dependencies:
```
npm install
```
Build the project:
```
npm run build
```
Test the server:
```
npm start
```

Python Setup:

Navigate to Python server:
```
cd python-server
```

Create virtual environment:

python3 -m venv .venv
source .venv/bin/activate  # macOS/Linux
# or .venv\Scripts\activate  # Windows

Install dependencies:
```
pip install -r requirements.txt
```
Test the server:
```
python3 src/server.py
```

Development

TypeScript:

Development mode with hot reload:
```
cd typescript-server
npm run dev
```
Build only:
```
cd typescript-server
npm run build
```

Python:

Run with virtual environment:

cd python-server
.venv/bin/python src/server.py

Run tests:

cd python-server
python3 test_server.py

Test Both Servers

Run the comprehensive test script to verify both implementations:

./test-servers.sh

This script will:

Build and test the TypeScript server
Run the Python server test suite
Verify both servers start correctly
Display usage instructions

Usage with MCP Clients

VS Code with GitHub Copilot

This project includes a pre-configured mcp.json file for VS Code integration:

Ensure the project is built (npm run build)
The server will be available as "example-mcp-server" in VS Code
Use GitHub Copilot agent mode to interact with the server

Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "example-mcp-server": {
      "command": "node",
      "args": ["/path/to/this/project/build/index.js"]
    }
  }
}

MCP Inspector

Test your server using the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Resource Examples

Static Resource

URI: file://README.md
Description: Project documentation and setup instructions

Dynamic Resource

URI Template: user://{userId}/profile
Example: user://123/profile
Description: Get user profile information by ID

Tool Examples

Calculator Tool

{
  "operation": "add",
  "a": 5,
  "b": 3
}

System Information

{
  "type": "time"
}

Data Generator

{
  "type": "user",
  "count": 3
}

Prompt Examples

Concept Explanation

{
  "concept": "Model Context Protocol",
  "audience": "intermediate"
}

Code Review

{
  "code": "function hello() { console.log('world'); }",
  "language": "javascript",
  "focus": "maintainability"
}

Project Planning

{
  "projectType": "web application",
  "requirements": "E-commerce platform with user authentication",
  "timeline": "3 months",
  "teamSize": "4"
}

Development

Project Structure

├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── .vscode/
│   └── mcp.json         # VS Code MCP configuration
├── package.json         # Project dependencies and scripts
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

Adding New Features

Adding a Resource

server.registerResource(
  "my-resource",
  "my-scheme://resource-path",
  {
    title: "My Resource",
    description: "Description of the resource",
    mimeType: "text/plain"
  },
  async (uri) => ({
    contents: [{
      uri: uri.href,
      text: "Resource content here"
    }]
  })
);

Adding a Tool

server.registerTool(
  "my-tool",
  {
    title: "My Tool",
    description: "What this tool does",
    inputSchema: {
      param1: z.string().describe("Parameter description")
    }
  },
  async ({ param1 }) => ({
    content: [{
      type: "text",
      text: `Result: ${param1}`
    }]
  })
);

Adding a Prompt

server.registerPrompt(
  "my-prompt",
  {
    title: "My Prompt",
    description: "What this prompt does",
    argsSchema: {
      input: z.string().describe("Input parameter")
    }
  },
  ({ input }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `Prompt text with ${input}`
      }
    }]
  })
);

Configuration

MCP Configuration

The .vscode/mcp.json file configures the server for VS Code:

Server name: example-mcp-server
Transport: stdio
Command: node
Arguments: Path to the compiled server

Update the path in mcp.json to match your project location.

Troubleshooting

Common Issues

"Cannot find module" errors
- Ensure dependencies are installed: npm install
- Rebuild the project: npm run build
Server not connecting
- Check that the path in mcp.json is correct
- Verify the build output exists in build/index.js
- Ensure Node.js is in your PATH
TypeScript compilation errors
- Check Node.js version (requires v18+)
- Clear node_modules and reinstall: rm -rf node_modules package-lock.json && npm install

Debug Mode

To debug the server, you can add logging:

console.error("Debug message", data);

Note: Use console.error() instead of console.log() for debugging when using stdio transport.

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT License - see LICENSE file for details.