Theagora MCP Server

Instructions

Implementation Reference

• src/tools/exchange.ts:8-43 (registration)

  The place_order tool is registered with the MCP server using server.tool(). This includes the tool name, description, input schema (lines 12-22), tool hints, and the handler function (lines 25-42).

  server.tool(
    'place_order',
    'Place a BID or ASK on the exchange. Immediate match if counter-order exists.',
    {
      side: z.enum(['BID', 'ASK']).describe('BID to buy, ASK to sell'),
      functionId: z.string().optional().describe('Specific function ID (required for ASK, optional for BID)'),
      category: z.string().optional().describe('Service category for loose matching (e.g., "code-generation", "data-analysis")'),
      description: z.string().optional().describe('What you want (BID) or what you offer (ASK)'),
      priceCents: z.number().describe('Max price to pay (BID) or asking price (ASK) in cents'),
      minReputation: z.number().optional().describe('BID only: minimum provider reputation (0-1)'),
      maxLatencyMs: z.number().optional().describe('BID only: maximum acceptable P95 latency in ms'),
      expiresAt: z.string().optional().describe('ISO 8601 expiry time. Omit for good-til-cancelled'),
      metadata: z.record(z.any()).optional().describe('Optional metadata'),
      input: z.record(z.any()).optional().describe('Input data to pass to the function (e.g. {"text": "hello"}). For auto-executable functions, this is sent directly to the provider endpoint.'),
      dryRun: z.boolean().optional().describe('Simulate order without creating records or locking funds. Returns what WOULD match, including input validation results.'),
    },
    { destructiveHint: true, idempotentHint: false, openWorldHint: true },
    async (params) => {
      const result = await client.placeOrder({
        side: params.side,
        functionId: params.functionId,
        category: params.category,
        description: params.description,
        priceCents: params.priceCents,
        minReputation: params.minReputation,
        maxLatencyMs: params.maxLatencyMs,
        expiresAt: params.expiresAt,
        metadata: params.metadata,
        input: params.input,
        dryRun: params.dryRun,
      });
      return {
        content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
      };
    }
  );

• src/tools/exchange.ts:12-22 (schema)

  Input validation schema using zod for the place_order tool. Defines all parameters: side (BID/ASK), functionId, category, description, priceCents, minReputation, maxLatencyMs, expiresAt, metadata, input, and dryRun with their types and descriptions.

  side: z.enum(['BID', 'ASK']).describe('BID to buy, ASK to sell'),
  functionId: z.string().optional().describe('Specific function ID (required for ASK, optional for BID)'),
  category: z.string().optional().describe('Service category for loose matching (e.g., "code-generation", "data-analysis")'),
  description: z.string().optional().describe('What you want (BID) or what you offer (ASK)'),
  priceCents: z.number().describe('Max price to pay (BID) or asking price (ASK) in cents'),
  minReputation: z.number().optional().describe('BID only: minimum provider reputation (0-1)'),
  maxLatencyMs: z.number().optional().describe('BID only: maximum acceptable P95 latency in ms'),
  expiresAt: z.string().optional().describe('ISO 8601 expiry time. Omit for good-til-cancelled'),
  metadata: z.record(z.any()).optional().describe('Optional metadata'),
  input: z.record(z.any()).optional().describe('Input data to pass to the function (e.g. {"text": "hello"}). For auto-executable functions, this is sent directly to the provider endpoint.'),
  dryRun: z.boolean().optional().describe('Simulate order without creating records or locking funds. Returns what WOULD match, including input validation results.'),

• src/tools/exchange.ts:25-42 (handler)

  The handler function that executes the place_order tool logic. It receives validated params, calls client.placeOrder() with all parameters, and returns the result as formatted JSON text content.

  async (params) => {
    const result = await client.placeOrder({
      side: params.side,
      functionId: params.functionId,
      category: params.category,
      description: params.description,
      priceCents: params.priceCents,
      minReputation: params.minReputation,
      maxLatencyMs: params.maxLatencyMs,
      expiresAt: params.expiresAt,
      metadata: params.metadata,
      input: params.input,
      dryRun: params.dryRun,
    });
    return {
      content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }],
    };
  }

• src/client.ts:239-253 (helper)

  The placeOrder API client method that makes the actual HTTP POST request to /orders endpoint. Takes the order parameters and returns the API response.

  async placeOrder(body: {
    side: 'BID' | 'ASK';
    functionId?: string;
    category?: string;
    description?: string;
    priceCents: number;
    minReputation?: number;
    maxLatencyMs?: number;
    expiresAt?: string;
    metadata?: Record<string, any>;
    input?: Record<string, any>;
    dryRun?: boolean;
  }): Promise<any> {
    return this.request('/orders', { method: 'POST', body });
  }

• src/index.ts:28-28 (registration)

  Registration call that invokes registerExchangeTools to register the place_order tool and other exchange-related tools with the MCP server.

  registerExchangeTools(server, client);