toyMCP To-Do List Server

This is a simple example server implementing a To-Do list CRUD API using the Model Context Protocol (MCP) concepts, specifically using JSON-RPC 2.0 over HTTP.

It uses Node.js, Express, and PostgreSQL (via Docker) for persistence.

Components

This project consists of two main components:

1. MCP Server: A JSON-RPC based API server for managing todo items

2. Agent Framework: A natural language interface to the MCP server using AI models

Setup

1. Prerequisites:

2. Clone the repository (if applicable):

# git clone ...
    # cd toyMCP

3. Install Dependencies:

npm install

4. Start PostgreSQL Database:

Make sure Docker Desktop (or the Docker daemon) is running.

docker compose up -d db

This will start a PostgreSQL container named `toymcp_db` in the background and create a persistent volume for its data.

5. Run the Server:

npm start

The server will initialize the database schema if necessary and start listening on `http://localhost:3000` (or the port specified by the `PORT` environment variable).

The JSON-RPC endpoint is `http://localhost:3000/rpc`.

The Swagger API documentation UI is available at `http://localhost:3000/api-docs`.

Clean Server Start

If you need to ensure the server starts with a completely fresh database (e.g., before running manual end-to-end tests or to reset state), you can use the `clean_start.sh` script:

1. Stop the running server (if any) by pressing `Ctrl+C` in the terminal where it's running.

2. Ensure the script is executable:

chmod +x clean_start.sh

3. Run the script:

./clean_start.sh

This script will stop and remove the database container (`docker compose down`), restart it (`docker compose up -d db`), and then start the Node.js server (`npm start`).

Running Tests

Ensure the PostgreSQL container is running (`docker compose up -d db`).

Tests are separated into `tests/unit_tests` and `tests/integration_tests`. The following command runs all tests:

npm test

Running Coverage Report

npm run coverage

This will output a summary to the terminal and generate a detailed HTML report in the `coverage/lcov-report/` directory, reflecting coverage from both unit and integration tests.

Running End-to-End Test Script

The project includes an orchestrator script (`run_full_test.sh`) that performs a full sequence of tests using `curl` against a live server, including cleaning the database beforehand and providing a summary report. This is the recommended way to perform a manual end-to-end check.

Prerequisites: `curl`, `jq`

chmod +x run_full_test.sh test_server.sh # Ensure scripts are executable
./run_full_test.sh

API Documentation

Interactive API documentation is available via Swagger UI both locally (when the server is running) and deployed via GitHub Pages:

• Local Swagger UI: `http://localhost:3000/api-docs`
• GitHub Pages Swagger UI: `https://izaqyos.github.io/toyMCP/swagger-ui/`

The documentation is generated automatically from JSDoc comments in `src/swagger_definitions.js` using `swagger-jsdoc`.

API Usage

Authentication

Most API endpoints require authentication using a JSON Web Token (JWT).

1. Login: First, send a POST request to `/auth/login` with your username and password in the JSON body:

curl -X POST -H "Content-Type: application/json" \
         -d '{"username": "testuser", "password": "password123"}' \
         http://localhost:3000/auth/login

*Success Response:*

{
        "message": "Login successful",
        "user": { "id": 1, "username": "testuser" },
        "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
    }

2. Use Token: Copy the received `token` value. For subsequent requests to protected endpoints (like `/rpc`), include it in the `Authorization` header as a Bearer token:

TOKEN="YOUR_JWT_TOKEN_HERE" # Replace with the actual token
    curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{"jsonrpc": "2.0", "method": "mcp.discover", "id": 1}' \
         http://localhost:3000/rpc

JSON-RPC Endpoint (`/rpc`)

Send POST requests to `http://localhost:3000/rpc` with `Content-Type: application/json`, an `Authorization: Bearer ` header, and a JSON-RPC 2.0 payload in the body.

Available Methods:

• `todo.list`: Lists all todo items.
• `todo.add`: Adds a new todo item (`params: { "text": "..." }`).
• `todo.remove`: Removes a todo item (`params: { "id": ... }`).
• `mcp.discover`: Describes the service and its available methods.

Example Tool: `curl` (assuming you have a valid $TOKEN obtained via `/auth/login`)

• Discover Service (`mcp.discover`)

curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{"jsonrpc": "2.0", "method": "mcp.discover", "id": 1}' \
         http://localhost:3000/rpc

*Success Response (example):*

{
        "jsonrpc": "2.0",
        "result": {
            "mcp_version": "1.0.0",
            "name": "ToyMCP Todo Service",
            "description": "A simple To-Do list manager implementing MCP concepts.",
            "methods": [
                {"name": "todo.list", ...},
                {"name": "todo.add", ...},
                {"name": "todo.remove", ...},
                {"name": "mcp.discover", ...}
            ]
        },
        "id": 1
    }

• Add Item (`todo.add`)

curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{"jsonrpc": "2.0", "method": "todo.add", "params": {"text": "Buy groceries"}, "id": 1}' \
         http://localhost:3000/rpc

*Success Response:*

{
        "jsonrpc": "2.0",
        "result": {
            "id": 1,
            "text": "Buy groceries",
            "created_at": "2025-04-07T16:15:00.123Z"
        },
        "id": 1
    }

• List Items (`todo.list`)

curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{"jsonrpc": "2.0", "method": "todo.list", "id": 2}' \
         http://localhost:3000/rpc

*Success Response (example):*

{
        "jsonrpc": "2.0",
        "result": [
            {
                "id": 1,
                "text": "Buy groceries",
                "created_at": "2025-04-07T16:15:00.123Z"
            }
            // ... other items
        ],
        "id": 2
    }

• Remove Item (`todo.remove`)

(Assuming an item with ID 1 exists)

curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 1}, "id": 3}' \
         http://localhost:3000/rpc

*Success Response:*

{
        "jsonrpc": "2.0",
        "result": {
            "id": 1,
            "text": "Buy groceries",
            "created_at": "2025-04-07T16:15:00.123Z"
        },
        "id": 3
    }

• Error Response Example (Item Not Found)

curl -X POST -H "Content-Type: application/json" \
         -H "Authorization: Bearer $TOKEN" \
         -d '{"jsonrpc": "2.0", "method": "todo.remove", "params": {"id": 999}, "id": 4}' \
         http://localhost:3000/rpc

*Response:*

{
        "jsonrpc": "2.0",
        "error": {
            "code": 1001,
            "message": "Todo item with ID 999 not found"
        },
        "id": 4
    }

Agent Framework

The repository includes an AI-powered agent framework that provides a natural language interface to the MCP server. The agent uses either local Ollama models or OpenAI's cloud-based models to interpret user instructions and perform the appropriate actions on the todo list.

Architecture

┌───────────────┐    ┌────────────────┐    ┌───────────────┐
│ LLM Provider  │◄───┤ Agent Framework├───►│  toyMCP API   │
│ (Ollama/Cloud)│    │                │    │  (Todo Server)│
└───────────────┘    └────────────────┘    └───────────────┘

Setup and Usage

The agent framework is located in the `agent-framework/` directory. To use it:

1. Set up the environment:

cd agent-framework
   npm install
   cp .env-example .env    # Configure settings as needed
   npm run build

2. Use natural language to manage your todo list:

# Add a task
   node index.js "Add milk to my shopping list"

   # List all tasks
   node index.js "What's on my todo list?"

   # Remove a task
   node index.js "Remove the shopping task"
   
   # Debug mode
   node index.js --debug "Add a reminder to call mom"

For detailed documentation on the agent framework, refer to:

• `agent-framework/README.md`: Setup and usage instructions
• `agent-framework/ARCHITECTURE.md`: Technical design and interaction flow
• `agent-framework/CHANGELOG.md`: Development history and changes