Intent MCP Server
A Model Context Protocol (MCP) server that processes natural language intents into structured, actionable formats. This server provides a robust API for managing and processing intents with a focus on extensibility and reliability.
Overview
This project implements an intent processing architecture that transforms natural language inputs into structured objects and generates executable workflows. It focuses on maintainability, type safety, and extensibility while providing a clean API for intent management.
Features
- 🎯 Intent Processing: Create, retrieve, and process intents through a well-defined API
- 🔍 Natural Language Understanding: Parse and understand raw user intentions
- 🧩 Intent Decomposition: Transform intentions into structured objects with goals and constraints
- 💾 Flexible Storage: Pluggable storage system with built-in in-memory implementation
- 📝 Type Safety: Full TypeScript implementation with comprehensive type definitions
- 🛡️ Error Handling: Robust error handling and logging system
- 🧪 Testing: Comprehensive test suite with Jest
- 📚 API Documentation: Clear API documentation and examples
Prerequisites
- Node.js (v18 or higher)
- npm or yarn
Installation
- Clone the repository:```bash
git clone https://github.com/openpandacodes/intent-mcp-server.git
cd intent-mcp-server
2. Install dependencies:```bash
npm install
- Create a
.envfile in the root directory:```bash
cp .env.example .env
4. Update the `.env` file with your configuration settings.
## Configuration
The server can be configured using environment variables:
- `NODE_ENV`: Environment (development, production, test)
- `PORT`: Server port (default: 3000)
- `LOG_LEVEL`: Logging level (debug, info, warn, error)
## Usage
### Development
Start the development server with hot reloading:```bash
npm run dev
Production
Build and start the production server:```bash
npm run build
npm start
### Testing
Run tests:```bash
npm test
Run tests with coverage:```bash
npm run test:coverage
## API Endpoints
### Intent Management
- `POST /api/intent`: Create a new intent```bash
curl -X POST http://localhost:3000/api/intent \
-H "Content-Type: application/json" \
-d '{"rawIntent": "Your natural language intent here"}'
```
- `GET /api/intent/:id`: Get an intent by ID```bash
curl -X GET http://localhost:3000/api/intent/YOUR_INTENT_ID
```
Additional endpoints are documented in the API specification.
### Health Check
- `GET /health`: Check server health status
## Architecture
The server follows a clean architecture pattern with distinct layers:
1. **Controllers**: Handle HTTP requests and responses
2. **Services**: Implement core business logic and intent processing
3. **Storage**: Manage data persistence with pluggable implementations
4. **Models**: Define data structures and types
### Key Components
- `IntentController`: Handles intent-related HTTP endpoints
- `IntentService`: Core service for intent processing
- `StorageInterface`: Abstract storage layer
- `InMemoryStorage`: Reference implementation of storage interface
### Project Structure```
intent-mcp-server/
├── src/
│ ├── controllers/ # HTTP request handlers
│ ├── services/ # Business logic implementation
│ │ └── __tests__/ # Service tests
│ ├── storage/ # Storage implementations
│ ├── models/ # Type definitions
│ └── utils/ # Utility functions
├── tests/ # Test suites
└── config/ # Configuration files
Intent Structure
The system structures intentions into formal objects:typescript
interface Intent {
id: string;
rawIntent: string;
processed: {
goals: Goal[];
constraints: Constraint[];
metadata: Record<string, unknown>;
};
status: "pending" | "processing" | "completed" | "failed";
createdAt: Date;
updatedAt: Date;
}
Error Handling
The server implements comprehensive error handling:
- Custom error classes for different types of errors
- Proper HTTP status codes and error responses
- Structured logging for debugging and monitoring
- Validation using TypeScript types
Contributing
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'feat: Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Create a Pull Request
Please ensure your code:
- Follows the existing style and conventions
- Includes appropriate tests
- Updates documentation as needed
- Uses conventional commit messages
License
MIT License - see LICENSE file for details
