ruvnet--ruflo/ruflo/docs/TOOLS.md

Adding Custom MCP Tools

Overview

MCP (Model Context Protocol) tools let the AI call your backend services. Each tool has:

• A definition (name, description, input schema) — shown to the AI
• A handler in executeTool() — routes the call to your backend

Step-by-Step

1. Add your backend URL

In mcp-bridge/index.js, add your service to CLOUD_FUNCTIONS:

const CLOUD_FUNCTIONS = {
  myService: process.env.MY_SERVICE_URL || "https://my-service-abc123.run.app",
};

2. Define the tool

Add a tool object to the TOOLS array:

{
  name: "lookup_customer",
  description: "Look up a customer by ID or name. Returns profile, account status, and recent activity.",
  inputSchema: {
    type: "object",
    properties: {
      customerId: { type: "string", description: "Customer ID (e.g., 'CUST-1234')" },
      name: { type: "string", description: "Customer name to search" },
    },
    required: [],  // neither is required — the AI can provide either
  },
}

Tips for good tool descriptions:

• Be specific about what it does and what it returns
• Include example values in property descriptions
• The AI uses descriptions to decide when to call the tool

3. Add the handler

In executeTool(), add a case for your tool:

case "lookup_customer":
  return callCloudFunction(CLOUD_FUNCTIONS.myService, {
    action: "get_customer",
    customerId: args.customerId,
    name: args.name,
  });

4. Update the system prompt

In config/config.json, add the tool to systemPrompt so the AI knows when to use it:

3. **lookup_customer** — Look up customer profiles and account details.
   USE FOR: "who is customer X?", "find customer", any question mentioning a customer ID.

Supported Input Types

JSON Schema Type	Example
string	{ type: "string" }
number	{ type: "number" }
boolean	{ type: "boolean" }
array	{ type: "array", items: { type: "string" } }
object	{ type: "object" }
enum	{ type: "string", enum: ["a", "b", "c"] }

Backend Response Format

Your Cloud Function should return JSON. The MCP bridge wraps it in the MCP response format automatically.

// Your backend returns:
{ "customer": { "id": "CUST-1234", "name": "Jane Doe", "status": "active" } }

// MCP bridge wraps it as:
{
  "jsonrpc": "2.0",
  "result": {
    "content": [{ "type": "text", "text": "{\"customer\":{...}}" }]
  }
}

Multiple Actions per Tool

A single tool can support multiple actions:

// Tool definition with enum actions
{
  name: "manage_orders",
  description: "Manage orders: list, search, create, or update.",
  inputSchema: {
    type: "object",
    properties: {
      action: { type: "string", enum: ["list", "search", "create", "update"] },
      orderId: { type: "string" },
      query: { type: "string" },
      data: { type: "object" },
    },
    required: ["action"],
  },
}

// Handler routes based on action
case "manage_orders": {
  const payload = { action: args.action };
  if (args.action === "search") payload.query = args.query;
  if (args.action === "create") payload.data = args.data;
  if (args.orderId) payload.orderId = args.orderId;
  return callCloudFunction(CLOUD_FUNCTIONS.orders, payload);
}

Testing Tools

# List all registered tools
curl -s -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq '.result.tools[].name'

# Call a specific tool
curl -s -X POST http://localhost:3001/mcp \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc":"2.0","id":1,"method":"tools/call",
    "params":{"name":"lookup_customer","arguments":{"customerId":"CUST-1234"}}
  }' | jq '.result.content[0].text' -r | jq .