Content
# 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.
```typescript
// 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.
```typescript
// 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.
```typescript
// 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.
```typescript
// 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.
```typescript
// 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
1. **Clone and install dependencies:**
```bash
npm install
```
2. **Build the server:**
```bash
npm run build
```
3. **Test the server:**
```bash
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
1. **Configure Claude Desktop** by editing your config file:
```bash
# macOS/Linux
~/.config/Claude/claude_desktop_config.json
# Windows
%APPDATA%\Claude\claude_desktop_config.json
```
2. **Add your server configuration:**
```json
{
"mcpServers": {
"hello-world-mcp": {
"command": "node",
"args": ["/absolute/path/to/hello_world/build/index.js"]
}
}
}
```
3. **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
1. **VS Code Integration**: Use the `.vscode/mcp.json` configuration to debug your server directly in VS Code.
2. **Check Claude Logs**:
```bash
# macOS
tail -f ~/Library/Logs/Claude/mcp*.log
# Linux
tail -f ~/.local/share/Claude/logs/mcp*.log
```
3. **Test Manually**: Run the server directly and test tool responses:
```bash
npm start
```
## Converting Your Own Services
To convert your existing services to MCP tools, follow this pattern:
1. **Identify Service Methods**: List all the functions/methods your service exposes
2. **Define Tool Schema**: Use Zod to create input validation schemas
3. **Implement Tool Logic**: Wrap your service calls in MCP tool handlers
4. **Handle Errors**: Implement proper error handling and user-friendly messages
5. **Test Integration**: Verify tools work with Claude Desktop or other MCP clients
### Example Pattern:
```typescript
// 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
1. **Explore the Code**: Check out `src/index.ts` to see the implementation patterns
2. **Add Your Tools**: Replace the example tools with your actual service methods
3. **Deploy**: Consider deployment options for production use
4. **Scale**: Add more sophisticated error handling, logging, and monitoring
## Resources
- [Model Context Protocol Documentation](https://modelcontextprotocol.io)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/typescript-sdk)
- [Claude Desktop](https://claude.ai/download)
- [MCP Examples Gallery](https://github.com/modelcontextprotocol/examples)
## License
ISC License - Feel free to use this as a starting point for your own MCP servers!
