xyz-abc-30/MCP-Server-setup

Example MCP Server

A complete Model Context Protocol (MCP) server implementation with TypeScript boilerplate code. This server provides example tools and resources for user and project management.

Features

Tools

• get_user: Retrieve user information by ID
• list_users: List all users in the system
• create_user: Create a new user with validation
• get_projects: Get projects with optional status filtering

Resources

• users://all: Complete JSON list of all users
• projects://all: Complete JSON list of all projects
• system://status: Current system status and statistics

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager

Installation & Setup

1. Clone or Create Project Directory

mkdir my-mcp-server
cd my-mcp-server

2. Initialize the Project

Create the following file structure:

my-mcp-server/
├── src/
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

3. Install Dependencies

npm install

This will install:

• @modelcontextprotocol/sdk: Core MCP SDK
• typescript: TypeScript compiler
• @types/node: Node.js type definitions

4. Set Up Source Files

1. Create a src directory:

   mkdir src
   

2. Copy the main server code into src/index.ts (provided in the artifact above)

5. Build the Project

npm run build

This compiles the TypeScript code to JavaScript in the build/ directory.

Running the Server

Development Mode

npm run dev

This builds and runs the server, outputting status to stderr.

Production Mode

npm start

Runs the compiled server from the build directory.

Watch Mode (Development)

npm run watch

Automatically rebuilds when source files change.

Testing the Server

The MCP server communicates via stdio (standard input/output). You can test it using:

1. Direct JSON-RPC Communication

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npm start

2. Using Claude Desktop or Compatible MCP Client

Add to your Claude Desktop configuration:

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

Configuration

Environment Variables

You can extend the server to use environment variables:

export MCP_SERVER_PORT=3000
export MCP_SERVER_LOG_LEVEL=debug

Custom Configuration

Create a config.json file:

{
  "server": {
    "name": "my-custom-mcp-server",
    "version": "1.0.0"
  },
  "features": {
    "enableUserCreation": true,
    "maxUsers": 1000
  }
}

Development

Project Structure

my-mcp-server/
├── src/
│   ├── index.ts          # Main server implementation
│   ├── handlers/         # Tool and resource handlers
│   ├── types/            # TypeScript type definitions
│   └── utils/            # Utility functions
├── build/                # Compiled JavaScript (generated)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Adding New Tools

1. Add tool definition to the ListToolsRequestSchema handler:

{
  name: "my_new_tool",
  description: "Description of what the tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "Parameter description" }
    },
    required: ["param1"]
  }
}

2. Add handler in the CallToolRequestSchema handler:

case "my_new_tool":
  return this.handleMyNewTool(args as { param1: string });

3. Implement the handler method:

private async handleMyNewTool(args: { param1: string }) {
  // Your tool logic here
  return {
    content: [{
      type: "text" as const,
      text: `Result: ${args.param1}`
    }]
  };
}

Adding New Resources

1. Add resource definition to ListResourcesRequestSchema handler
2. Add handler case in ReadResourceRequestSchema handler
3. Return appropriate content with correct MIME type

Debugging

Enable Debug Logging

DEBUG=mcp:* npm run dev

Common Issues

1. Port already in use: The server uses stdio by default, no ports
2. Permission denied: Ensure the built file is executable
3. Module not found: Run npm install and npm run build

Logs

Server logs are output to stderr to avoid interfering with stdio communication:

npm start 2>server.log

Deployment

Local Installation

npm run build
npm link

Then use example-mcp-server globally.

Docker (Optional)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
CMD ["node", "build/index.js"]

API Reference

Tools

get_user

• Parameters: { userId: number }
• Returns: User object with id, name, email, role
• Errors: User not found

list_users

• Parameters: None
• Returns: Array of all user objects

create_user

• Parameters: { name: string, email: string, role: "admin"|"user" }
• Returns: Created user object
• Errors: Invalid email, duplicate email

get_projects

• Parameters: { status?: "active"|"planning"|"completed" }
• Returns: Array of project objects (filtered if status provided)

Resources

users://all

• Type: application/json
• Content: Complete user list

projects://all

• Type: application/json
• Content: Complete project list

system://status

• Type: text/plain
• Content: System status report

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Check the MCP documentation
• Open an issue on GitHub
• Review the server logs for debugging information