Build Your Own MCP Server for OpenClaw

| Field | Decision |
| --- | --- |
| Tool name | lookup_playbook_rule |
| User goal | Return one approved rule for a repeatable workflow |
| Inputs | topic: string |
| Output | { title: string, rule: string, source: string } |
| Allowed resources | ./playbooks/*.json only |
| Forbidden actions | No writes, no shell commands, no network |
| Timeout | 3 seconds |
| Error codes | NOT_FOUND, INVALID_INPUT, ACCESS_DENIED |
| Verification prompt | Ask for the rule for "release checklist" |

import { readFile } from 'node:fs/promises';
import { join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

const __dirname = fileURLToPath(new URL('.', import.meta.url));
const DATA_FILE = join(__dirname, '../data/playbooks.json');
const REQUEST_TIMEOUT_MS = 3_000;

type PlaybookRule = {
  topic: string;
  title: string;
  rule: string;
  source: string;
};

const server = new McpServer({ name: 'custom-playbook-mcp', version: '1.0.0' });

async function readRules(): Promise<PlaybookRule[]> {
  // Allowlist: read only ./data/playbooks.json. Never accept user-controlled file paths.
  const raw = await readFile(DATA_FILE, 'utf8');
  return z.array(
    z.object({
      topic: z.string(),
      title: z.string(),
      rule: z.string(),
      source: z.string(),
    })
  ).parse(JSON.parse(raw));
}

function errorPayload(code: 'INVALID_INPUT' | 'NOT_FOUND' | 'ACCESS_DENIED', message: string) {
  return JSON.stringify({ error: code, message });
}

server.registerTool(
  'lookup_playbook_rule',
  {
    description: 'Return one approved rule from the local playbook.',
    inputSchema: z.object({ topic: z.string().min(1) }),
  },
  async ({ topic }) => {
    const normalizedTopic = topic.trim().toLowerCase();
    if (!normalizedTopic) {
      return {
        content: [{ type: 'text', text: errorPayload('INVALID_INPUT', 'topic must not be empty') }],
      };
    }

    const task = (async () => {
      const rules = await readRules();
      const match = rules.find((item) => item.topic.toLowerCase() === normalizedTopic);
      if (!match) {
        return {
          content: [{ type: 'text', text: errorPayload('NOT_FOUND', `No rule found for "${topic}"`) }],
        };
      }

      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify({
              title: match.title,
              rule: match.rule,
              source: match.source,
            }),
          },
        ],
      };
    })();

    return await Promise.race([
      task,
      new Promise<never>((_, reject) =>
        setTimeout(() => reject(new Error('ACCESS_DENIED: request timed out or touched a forbidden resource')), REQUEST_TIMEOUT_MS)
      ),
    ]);
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);