joempora/rw-mcp-srv

Containerized PHP MCP server using ReliefWeb API v2

This project provides a simple containerized PHP server that acts as a ReliefWeb Context Provider (MCP). It fetches disaster and humanitarian reports from the ReliefWeb API, caches them, and serves them via a JSON-RPC 2.0 interface, allowing AI agents to access relevant context.

Prerequisites

To build and run this application, you'll need:

• Docker: For containerizing and running the application.
• PHP (version 8.2 or higher): While the application is containerized, understanding PHP is beneficial for development.
• Composer: PHP's dependency manager, used to install project dependencies like Guzzle.

Building

To build the Docker image for the MCP server, run this command in the directory containing the Dockerfile, composer.json, and other project files:

docker build -t mcp-reliefweb-php .

This command will:

1. Use a multi-stage build to efficiently install PHP dependencies with Composer.
2. Copy the application files into the container.
3. Prepare the image to run the PHP built-in web server.

Running

To run the containerized MCP server and map its port 8000 to your host's port 8000, use the following command:

docker run -p 8000:8000 mcp-reliefweb-php

The server will be accessible at http://localhost:8000.

Testing

The server exposes a JSON-RPC 2.0 endpoint at the root path (/) and expects POST requests with a JSON body.

1. Handshake

To verify the server's protocol version:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc": "2.0",
           "method": "mcp.server.handshake",
           "id": 1
         }' \
     http://localhost:8000/

Expected Response Example:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-05-14"
  }
}

2. Get Capabilities

To retrieve the server's capabilities (e.g., that it's a context provider):

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc": "2.0",
           "method": "mcp.server.get_capabilities",
           "id": 2
         }' \
     http://localhost:8000/

Expected Response Example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "capabilities": {
      "contextProvider": true
    }
  }
}

3. Provide Context

To request disaster and humanitarian reports based on a query:

curl -X POST \
     -H "Content-Type: application/json" \
     -d '{
           "jsonrpc": "2.0",
           "method": "mcp.server.provide_context",
           "params": {
             "query": "flood in Pakistan",
             "limit": 2
           },
           "id": 3
         }' \
     http://localhost:8000/

Expected Response Example:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "context": [
      {
        "type": "text",
        "text": "Pakistan Floods 2022: Rapid Needs Assessment (RNA) Report, Balochistan (29 Aug 2022): https://reliefweb.int/node/3880628\n\nPakistan: 2022 Floods Response Situation Report No. 1 (29 Aug 2022): https://reliefweb.int/node/3880629"
      }
    ]
  }
}

Configuration

Key application parameters are defined as constants within index.php:

• APPNAME: Application name for ReliefWeb API requests.
• CACHE_DIR: Directory used for caching API responses (defaults to ./cache).
• CACHE_TTL: Time-to-live for cache entries in seconds (defaults to 900 seconds or 15 minutes).

Notes on Cache Management

The application implements a simple file-based cache to reduce redundant calls to the ReliefWeb API. Cache cleanup is performed automatically when a cached item is retrieved if it has expired. For production environments with high traffic, consider implementing a separate, scheduled task (e.g., a cron job) to clean up expired cache files to optimize performance further.

License

This project is licensed under the MIT License.