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

1. Clone the repository:

git clone https://github.com/openpandacodes/intent-mcp-server.git

cd intent-mcp-server

2. Install dependencies:

npm install

3. Create a .env file in the root directory:

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:

npm run dev

Production

Build and start the production server:

npm run build

npm start

Testing

Run tests:

npm test

Run tests with coverage:

npm run test:coverage

API Endpoints

Intent Management

- POST /api/intent: Create a new intent

  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

  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:

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

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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