izaqyos/toyMCP

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:

   • Node.js (LTS version recommended)
   • npm (usually comes with Node.js)
   • Docker and Docker Compose

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 <token> 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