README.md•7.25 kB
# Demo MCP Server
A comprehensive boilerplate Model Context Protocol (MCP) server built with TypeScript using Domain-Driven Design patterns and dynamic component loading.
## 🚀 Features
- **Domain-Driven Design**: Clean architecture with separated concerns
- **Dynamic Component Loading**: File-based automatic loading of MCP components
- **TypeScript**: Full type safety and modern JavaScript features
- **Dependency Injection**: Modular and testable architecture
- **Example Components**: Ready-to-use tools, resources, and prompts
- **Comprehensive Logging**: Detailed startup and operation logging
- **Graceful Shutdown**: Proper cleanup and resource management
## 📁 Project Structure
```
src/
├── index.ts # Main entry point
├── types/ # Type definitions
│ └── index.ts # MCP interfaces and types
├── services/ # Business logic services
│ ├── index.ts # Services barrel export
│ └── module-loader-service.ts # Dynamic module loading
├── server/ # MCP server wrapper
│ ├── index.ts # Server barrel export
│ └── my-mcp-server.ts # Main server implementation
├── tools/ # MCP tools directory
│ ├── index.ts # Auto-loading tools
│ ├── calculator-tools.ts # Example arithmetic tools
│ └── text-processing-tools.ts # Example text tools
├── resources/ # MCP resources directory
│ ├── index.ts # Auto-loading resources
│ ├── system-info-resources.ts # System information
│ └── config-resources.ts # Configuration data
└── prompts/ # MCP prompts directory
├── index.ts # Auto-loading prompts
├── code-review-prompts.ts # Code analysis prompts
└── writing-assistance-prompts.ts # Writing help prompts
```
## 🛠️ Installation
1. **Clone the repository:**
```bash
git clone <repository-url>
cd demo-mcp-dev-1
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build the project:**
```bash
npm run build
```
## 🎯 Usage
### Development Mode
Run the server in development mode with hot reloading:
```bash
npm run dev
```
### Production Mode
Build and run the server in production:
```bash
npm run build
npm start
```
### Direct Execution
Run the compiled server directly:
```bash
node dist/index.js
```
## 🔧 Available Tools
### Calculator Tools
- `add` - Add two numbers
- `subtract` - Subtract two numbers
- `multiply` - Multiply two numbers
- `divide` - Divide two numbers (with zero-division protection)
### Text Processing Tools
- `transform-text` - Transform text (uppercase, lowercase, capitalize, reverse, word-count)
- `analyze-text` - Analyze text and provide detailed statistics
## 📚 Available Resources
### System Information
- `system://info` - System and environment information
- `env://{varName}` - Access environment variables
- `process://info` - Node.js process information
### Configuration
- `config://app` - Application configuration
- `settings://{category}/{key}` - Dynamic configuration settings
- `health://status` - Health and status information
## 📝 Available Prompts
### Code Review Prompts
- `review-code` - Comprehensive code review with focus areas
- `refactor-code` - Code refactoring suggestions
- `document-code` - Generate code documentation
### Writing Assistance
- `write-email` - Professional email generation
- `write-technical-doc` - Technical documentation creation
- `summarize-meeting` - Meeting summary generation
## 🏗️ Architecture
### Domain-Driven Design
The project follows DDD principles with clear separation of concerns:
- **Types**: Domain interfaces and contracts
- **Services**: Business logic and operations
- **Server**: Infrastructure and MCP integration
- **Components**: MCP-specific implementations (tools, resources, prompts)
### Dynamic Component Loading
The `ModuleLoaderService` automatically discovers and loads MCP components:
1. Scans component directories for TypeScript/JavaScript files
2. Dynamically imports modules using file URLs
3. Validates module contracts
4. Registers components with the MCP server
### Dependency Injection
The `MyMCPServer` class uses dependency injection patterns:
- Abstract base classes for extensibility
- Interface-based dependencies
- Configurable service injection
- Clean separation between SDK and business logic
## 🔌 Adding New Components
### Adding a New Tool
1. Create a new file in `src/tools/` (e.g., `my-new-tool.ts`)
2. Export an MCP module with the required structure:
```typescript
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import type { MCPModule } from "../types/index.js";
async function register(server: McpServer): Promise<void> {
server.registerTool(
"my-tool",
{
title: "My Tool",
description: "Description of what my tool does",
inputSchema: {
param1: z.string().describe("First parameter"),
param2: z.number().describe("Second parameter")
}
},
async ({ param1, param2 }) => ({
content: [
{
type: "text",
text: `Tool result: ${param1} - ${param2}`
}
]
})
);
}
export const myNewTool: MCPModule = {
register,
metadata: {
name: "my-new-tool",
description: "My new tool implementation",
version: "1.0.0",
author: "Your Name"
}
};
export default myNewTool;
```
3. The tool will be automatically loaded on server startup!
### Adding a New Resource
1. Create a new file in `src/resources/` (e.g., `my-resource.ts`)
2. Export an MCP module following the same pattern as tools
3. Use `server.registerResource()` in the register function
### Adding a New Prompt
1. Create a new file in `src/prompts/` (e.g., `my-prompt.ts`)
2. Export an MCP module following the same pattern
3. Use `server.registerPrompt()` in the register function
## 🧪 Testing
Run the test suite:
```bash
npm test
```
Run linting:
```bash
npm run lint
```
Type checking:
```bash
npm run type-check
```
## 🔍 Debugging
The server provides comprehensive logging during startup and operation:
- Component discovery and loading
- Registration success/failure
- Server status and configuration
- Error details and stack traces
## 📊 Configuration
The server is configured in `src/index.ts`:
```typescript
const serverConfig: MCPServerConfig = {
name: "demo-mcp-server",
version: "1.0.0",
capabilities: {
tools: true,
resources: true,
prompts: true,
logging: true
}
};
```
## 🤝 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
This project is licensed under the MIT License - see the LICENSE file for details.
## 🙏 Acknowledgments
- Built with the [Model Context Protocol TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- Inspired by Domain-Driven Design principles
- Thanks to the MCP community for excellent documentation and examples