mcp_starter_server by riyajahamedi - MCP Server

Hello World MCP Server

A comprehensive example demonstrating how to convert your existing services into Model Context Protocol (MCP) servers.

What is MCP?

Model Context Protocol (MCP) is a standardized way for AI assistants like Claude to connect to external data sources and services. Think of it as a bridge that allows AI models to interact with your applications, databases, APIs, and business logic in a secure and controlled manner.

How to Convert Your Services to MCP Servers

This project demonstrates 5 common patterns for converting existing services into MCP tools:

1. Data Service → MCP Tool

Convert simple data retrieval services (like user management) into queryable tools.

// Your existing service method
getUserById(id: string): User | null

// Becomes an MCP tool
server.tool("get-user", "Retrieve user information by ID", ...)

2. API Service → MCP Tool

Expose external API calls as MCP tools for AI assistants to use.

// Your existing API service
getWeatherData(location: string): WeatherData

// Becomes an MCP tool
server.tool("get-weather", "Get current weather for a location", ...)

3. Database Service → MCP Tool

Convert database operations into searchable and queryable tools.

// Your existing database service
searchUsers(query: string): User[]

// Becomes an MCP tool
server.tool("search-users", "Search users by name or email", ...)

4. File System Service → MCP Tool

Transform file operations into tools AI can use to create and manage files.

// Your existing file service
createFile(filename: string, content: string): boolean

// Becomes an MCP tool
server.tool("create-file", "Create a new file with content", ...)

5. Business Logic Service → MCP Tool

Convert complex business rules and calculations into AI-accessible tools.

// Your existing business logic
calculateDiscount(amount: number, customerType: string): DiscountResult

// Becomes an MCP tool
server.tool("calculate-discount", "Calculate discount based on business rules", ...)

Key Benefits of MCP Servers

🔒 Secure Access: Controlled access to your data and services
⚡ Real-time Data: AI can access live, up-to-date information
🛠️ Custom Tools: Expose your business logic as tools the AI can use
📈 Scalable: Easy to deploy and manage across different environments
🔄 Standardized: Consistent interface for AI model interactions

Installation & Setup

Clone and install dependencies:
```
npm install
```
Build the server:
```
npm run build
```
Test the server:
```
npm start
```

Available Tools

This example server exposes 5 tools that demonstrate different patterns:

Tool	Description	Parameters
`get-user`	Retrieve user information by ID	`userId: string`
`get-weather`	Get current weather for a location	`location: string`
`search-users`	Search users by name or email	`query: string, limit?: number`
`create-file`	Create a new file with content	`filename: string, content: string`
`calculate-discount`	Calculate discount based on business rules	`amount: number, customerType: enum, itemCount: number`

Using with Claude Desktop

Configure Claude Desktop by editing your config file:

# macOS/Linux
~/.config/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

Add your server configuration:

{
  "mcpServers": {
    "hello-world-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/hello_world/build/index.js"]
    }
  }
}

Restart Claude Desktop and look for the MCP tools icon.

Development Scripts

npm run build - Build the TypeScript project
npm run start - Build and start the server
npm run dev - Watch mode for development
npm test - Run tests (placeholder)

Project Structure

hello_world/
├── src/
│   └── index.ts          # Main MCP server implementation
├── build/                # Compiled JavaScript output
├── .github/
│   └── copilot-instructions.md  # Copilot customization
├── .vscode/
│   └── mcp.json         # VS Code MCP configuration
├── package.json         # Project configuration
├── tsconfig.json        # TypeScript configuration
└── README.md           # This file

Debugging Your MCP Server

VS Code Integration: Use the .vscode/mcp.json configuration to debug your server directly in VS Code.

Check Claude Logs:

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Linux  
tail -f ~/.local/share/Claude/logs/mcp*.log

Test Manually: Run the server directly and test tool responses:
```
npm start
```

Converting Your Own Services

To convert your existing services to MCP tools, follow this pattern:

Identify Service Methods: List all the functions/methods your service exposes
Define Tool Schema: Use Zod to create input validation schemas
Implement Tool Logic: Wrap your service calls in MCP tool handlers
Handle Errors: Implement proper error handling and user-friendly messages
Test Integration: Verify tools work with Claude Desktop or other MCP clients

Example Pattern:

// Your existing service
class MyService {
  async getData(id: string): Promise<Data> {
    // Your existing logic
  }
}

// Convert to MCP tool
server.tool(
  "get-data",
  "Retrieve data by ID",
  {
    id: z.string().describe("The unique identifier"),
  },
  async ({ id }) => {
    try {
      const data = await myService.getData(id);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(data, null, 2),
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Error retrieving data: ${error.message}`,
          },
        ],
      };
    }
  }
);

Next Steps

Explore the Code: Check out src/index.ts to see the implementation patterns
Add Your Tools: Replace the example tools with your actual service methods
Deploy: Consider deployment options for production use
Scale: Add more sophisticated error handling, logging, and monitoring

Resources

License

ISC License - Feel free to use this as a starting point for your own MCP servers!