karx/kaaroMCP

Kaaro MCP Server

A robust Model Context Protocol (MCP) server implementation for the Kaaro Brain agent interface. This project has been refactored for maintainability, observability, and team collaboration.

🚀 Features

• MCP Protocol Support: Full implementation of the Model Context Protocol for AI agent communication
• Session Management: Robust session handling with automatic cleanup
• Comprehensive Logging: Detailed logging for debugging and monitoring
• Health Monitoring: Built-in health check endpoints
• TypeScript: Full type safety and modern development experience
• Testing: Comprehensive unit and integration tests
• Modular Architecture: Clean separation of concerns for maintainability

📁 Project Structure

kaaroMCP/
├── src/
│   ├── types/           # TypeScript type definitions
│   ├── utils/           # Utility functions (logger, etc.)
│   ├── services/        # Business logic services
│   ├── routes/          # HTTP route handlers
│   ├── middleware/      # Express middleware
│   ├── app.ts           # Main application class
│   └── index.ts         # Application entry point
├── tests/               # Unit and integration tests
├── dist/                # Compiled JavaScript output
├── package.json         # Dependencies and scripts
├── tsconfig.json        # TypeScript configuration
├── jest.config.js       # Test configuration
└── README.md           # This file

🛠️ Installation

1. Clone the repository:

git clone <repository-url>
cd kaaroMCP

2. Install dependencies:

npm install

3. Build the project:

npm run build

🏃‍♂️ Running the Server

Development Mode

npm run dev

Production Mode

npm start

The server will start on port 3000 by default. You can configure this using environment variables:

PORT=8080 npm start

📡 API Endpoints

MCP Protocol

• POST /mcp - Client-to-server communication
• GET /mcp - Server-to-client notifications (SSE)
• DELETE /mcp - Session termination

Health & Monitoring

• GET /health - Health check endpoint
• GET / - Server information

Example Health Response

{
  "status": "healthy",
  "timestamp": "2024-01-14T01:38:00.000Z",
  "server": {
    "name": "kaaro-mcp-server",
    "version": "1.0.0",
    "uptime": 125.5
  },
  "sessions": {
    "activeSessions": 2,
    "sessionIds": ["session-123", "session-456"]
  }
}

🔧 Configuration

The server can be configured through environment variables:

Production Configuration

NODE_ENV=production
PORT=8080
ALLOWED_HOSTS=yourdomain.com,api.yourdomain.com

🧪 Testing

Run all tests

npm test

Run tests in watch mode

npm run test:watch

Generate coverage report

npm run test:coverage

Test Structure

• Unit Tests: Individual component testing
• Integration Tests: End-to-end API testing
• Mocking: Console output and external dependencies

📊 Logging & Observability

The server includes comprehensive logging for observability:

Log Levels

• INFO: General information
• WARN: Warning conditions
• ERROR: Error conditions
• DEBUG: Debug information (development only)

Log Context

All logs include contextual information:

{
  "timestamp": "2024-01-14T01:38:00.000Z",
  "level": "info",
  "message": "Session initialized",
  "sessionId": "abc-123",
  "method": "POST",
  "path": "/mcp"
}

Monitoring Events

• Session lifecycle (created, initialized, closed)
• Request/response timing
• Tool invocations
• Resource access
• Error conditions

🔌 MCP Tools & Resources

Available Tools

• add: Addition calculator
• multiply: Multiplication calculator

Available Resources

• greeting://{name}: Dynamic greeting generator
• status://server: Server status information

Example Tool Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "add",
    "arguments": {
      "a": 5,
      "b": 3
    }
  }
}

🚀 Development

Adding New Tools

1. Modify src/services/mcpServer.ts
2. Add tool registration in setupTools()
3. Include logging and error handling
4. Add unit tests

Adding New Resources

1. Modify src/services/mcpServer.ts
2. Add resource registration in setupResources()
3. Include proper URI templates
4. Add integration tests

Code Style

• Use TypeScript strict mode
• Follow ESLint configuration
• Include comprehensive error handling
• Add logging for all major operations

📝 Scripts

🐛 Troubleshooting

Common Issues

1. Port already in use:

   PORT=8080 npm start
   

2. TypeScript compilation errors:

   npm run lint
   

3. Test failures:

   DEBUG=true npm test
   

Debug Mode

Enable detailed logging:

DEBUG=true npm run dev

🤝 Contributing

1. Create a feature branch
2. Write tests for new functionality
3. Ensure all tests pass
4. Update documentation
5. Submit a pull request

Development Workflow

# Start development server
npm run dev

# Run tests
npm test

# Check types
npm run lint

# Build for production
npm run build

📄 License

This project is licensed under the ISC License.

🙋‍♂️ Support

For questions or issues:

1. Check the troubleshooting section
2. Review the logs with DEBUG=true
3. Check existing issues
4. Create a new issue with detailed information

Made with ❤️ for the Kaaro Brain project