# 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:

1. **MCP Server Architecture**
   - How to structure an MCP server
   - Tool definitions and handlers
   - Resource management
   - Error handling patterns

2. **Best Practices**
   - TypeScript for type safety
   - Separation of concerns
   - Input validation and security
   - Error handling
   - Extensible architecture

3. **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

```bash
# 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:**
```json
{
  "name": "calculator",
  "arguments": {
    "operation": "add",
    "a": 10,
    "b": 5
  }
}
```

### 2. File Operations Tool
Read, write, list, and get info about files.

**Example:**
```json
{
  "name": "file_operations",
  "arguments": {
    "operation": "read",
    "path": "README.md"
  }
}
```

### 3. System Info Tool
Get system information (platform, memory, CPU, etc.).

**Example:**
```json
{
  "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:
```bash
export GOOGLE_ADK_ENABLED=true
```

### Next Steps for Full Integration

1. **Set up Google Actions Project**
   - Create a project in Google Cloud Console
   - Enable Actions API
   - Set up OAuth credentials

2. **Implement Webhook Server**
   - Use Express.js or similar
   - Handle fulfillment requests
   - Connect to MCP server tools

3. **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

1. Add to Claude Desktop configuration:
```json
{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/mcp-server-demo/dist/index.js"]
    }
  }
}
```

2. Restart Claude Desktop
3. 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
1. ✅ Understand the project structure
2. ✅ Run the server and test tools
3. ✅ Read through the code comments
4. ✅ Modify calculator tool to add new operations

### Intermediate Tasks
1. Add a new tool (e.g., `weather` tool using an API)
2. Implement resource caching
3. Add tool usage rate limiting
4. Create unit tests for tools

### Advanced Tasks
1. Implement full Google ADK webhook server
2. Add authentication/authorization
3. Implement tool chaining
4. Add streaming responses
5. Create a remote MCP server (HTTP transport)

## 📖 Resources

- [MCP Specification](https://modelcontextprotocol.io)
- [Google Actions Documentation](https://developers.google.com/assistant)
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)

## 🤝 Contributing

This is a learning project! Feel free to:
- Add more example tools
- Improve error handling
- Add tests
- Enhance documentation

## 📝 License

MIT

---

**Happy Learning! 🚀**