MCP Server Demo - Learning Project
A comprehensive learning project demonstrating how to build a Model Context Protocol (MCP) server with Google ADK integration using best practices.
🎯 Learning Objectives
This project teaches you:
-
MCP Server Architecture
- How to structure an MCP server
- Tool definitions and handlers
- Resource management
- Error handling patterns
-
Best Practices
- TypeScript for type safety
- Separation of concerns
- Input validation and security
- Error handling
- Extensible architecture
-
Google ADK Integration
- Integration points for Google Actions
- Analytics and logging
- Fulfillment handlers (placeholder)
📁 Project Structure
mcp-server-demo/
├── src/
│ ├── index.ts # Main server entry point
│ ├── tools/
│ │ ├── base-tool.ts # Base tool interface
│ │ ├── calculator.ts # Calculator tool example
│ │ ├── file-operations.ts # File operations tool
│ │ └── system-info.ts # System information tool
│ └── integrations/
│ └── google-adk.ts # Google ADK integration
├── package.json
├── tsconfig.json
└── README.md
🚀 Getting Started
Prerequisites
- Node.js 18+
- npm or yarn
Installation
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode (with auto-reload)
npm run dev
# Run the built server
npm start
🛠️ Available Tools
1. Calculator Tool
Perform basic mathematical operations.
Example:
{
"name": "calculator",
"arguments": {
"operation": "add",
"a": 10,
"b": 5
}
}
2. File Operations Tool
Read, write, list, and get info about files.
Example:
{
"name": "file_operations",
"arguments": {
"operation": "read",
"path": "README.md"
}
}
3. System Info Tool
Get system information (platform, memory, CPU, etc.).
Example:
{
"name": "system_info",
"arguments": {
"detail": "full"
}
}
🔌 Google ADK Integration
The project includes a Google ADK integration module that demonstrates:
- Analytics Logging: Track tool usage
- Fulfillment Handlers: Process Google Assistant requests (placeholder)
- Usage Statistics: Get insights into tool usage
Enabling Google ADK
Set the environment variable:
export GOOGLE_ADK_ENABLED=true
Next Steps for Full Integration
-
Set up Google Actions Project
- Create a project in Google Cloud Console
- Enable Actions API
- Set up OAuth credentials
-
Implement Webhook Server
- Use Express.js or similar
- Handle fulfillment requests
- Connect to MCP server tools
-
Deploy
- Deploy to Google Cloud Functions or Cloud Run
- Configure webhook URL in Actions Console
📚 Best Practices Demonstrated
1. Type Safety
- Full TypeScript implementation
- Strict type checking enabled
- Interface definitions for all tools
2. Security
- Path validation (prevents directory traversal)
- Input sanitization
- Error message sanitization
3. Error Handling
- Comprehensive try-catch blocks
- Meaningful error messages
- Graceful degradation
4. Code Organization
- Separation of concerns
- Modular tool architecture
- Clear abstraction layers
5. Extensibility
- Easy to add new tools (extend
BaseTool) - Plugin-like architecture
- Configuration-driven behavior
🧪 Testing Your MCP Server
Using Claude Desktop
- Add to Claude Desktop configuration:
{
"mcpServers": {
"demo": {
"command": "node",
"args": ["/path/to/mcp-server-demo/dist/index.js"]
}
}
}
- Restart Claude Desktop
- The tools should be available in Claude
Using MCP Client
You can also test with an MCP client library or create a simple test script.
🎓 Learning Path
Beginner Tasks
- ✅ Understand the project structure
- ✅ Run the server and test tools
- ✅ Read through the code comments
- ✅ Modify calculator tool to add new operations
Intermediate Tasks
- Add a new tool (e.g.,
weathertool using an API) - Implement resource caching
- Add tool usage rate limiting
- Create unit tests for tools
Advanced Tasks
- Implement full Google ADK webhook server
- Add authentication/authorization
- Implement tool chaining
- Add streaming responses
- Create a remote MCP server (HTTP transport)
📖 Resources
🤝 Contributing
This is a learning project! Feel free to:
- Add more example tools
- Improve error handling
- Add tests
- Enhance documentation
📝 License
MIT
Happy Learning! 🚀