Sidearm MCP Server

Instructions

Implementation Reference

• src/tools/check-job.ts:24-68 (handler)

  Main handler function for check_job tool that polls the API for job status, formats the response with status, progress, timestamps, and result data, and handles errors.

  async ({ job_id }) => {
    try {
      const result = (await api.get(
        `/api/v1/jobs/${encodeURIComponent(job_id)}`,
      )) as JobResponse;
  
      const lines: string[] = [
        `Status: ${result.status}`,
      ];
  
      if (result.progress !== undefined) {
        lines.push(`Progress: ${result.progress}%`);
      }
      if (result.created_at) {
        lines.push(`Created: ${result.created_at}`);
      }
      if (result.completed_at) {
        lines.push(`Completed: ${result.completed_at}`);
      }
      if (result.error) {
        lines.push(`\nError: ${result.error}`);
      }
      if (result.result) {
        lines.push(`\nResult:\n${JSON.stringify(result.result, null, 2)}`);
      }
  
      if (result.status === "queued" || result.status === "processing") {
        lines.push(`\nJob is still running. Call check_job again in a few seconds.`);
      }
  
      return {
        content: [{ type: "text" as const, text: lines.join("\n") }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
          },
        ],
        isError: true as const,
      };
    }
  },

• src/tools/check-job.ts:22-23 (schema)

  Input schema definition using zod that validates the job_id parameter as a string.

    job_id: z.string().describe("The job ID returned by a previous tool call"),
  },

• src/tools/check-job.ts:5-13 (schema)

  TypeScript interface JobResponse that defines the structure of the API response including id, status, progress, result, error, and timestamps.

  interface JobResponse {
    id: string;
    status: string;
    progress?: number;
    result?: unknown;
    error?: string;
    created_at?: string;
    completed_at?: string;
  }

• src/tools/check-job.ts:16-69 (registration)

  Tool registration with server.tool() that registers the check_job tool with its name, description, input schema, and handler function.

  server.tool(
    "check_job",
    "Check the status of an asynchronous job (from run_algorithm, protect_media, or detect_ai). " +
      "Returns status (queued, processing, completed, failed), progress percentage, " +
      "and result data including download URLs when complete.",
    {
      job_id: z.string().describe("The job ID returned by a previous tool call"),
    },
    async ({ job_id }) => {
      try {
        const result = (await api.get(
          `/api/v1/jobs/${encodeURIComponent(job_id)}`,
        )) as JobResponse;
  
        const lines: string[] = [
          `Status: ${result.status}`,
        ];
  
        if (result.progress !== undefined) {
          lines.push(`Progress: ${result.progress}%`);
        }
        if (result.created_at) {
          lines.push(`Created: ${result.created_at}`);
        }
        if (result.completed_at) {
          lines.push(`Completed: ${result.completed_at}`);
        }
        if (result.error) {
          lines.push(`\nError: ${result.error}`);
        }
        if (result.result) {
          lines.push(`\nResult:\n${JSON.stringify(result.result, null, 2)}`);
        }
  
        if (result.status === "queued" || result.status === "processing") {
          lines.push(`\nJob is still running. Call check_job again in a few seconds.`);
        }
  
        return {
          content: [{ type: "text" as const, text: lines.join("\n") }],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text" as const,
              text: `Error: ${err instanceof Error ? err.message : String(err)}`,
            },
          ],
          isError: true as const,
        };
      }
    },
  );

• src/index.ts:9-47 (registration)

  Import and registration call of the check_job tool in the main server initialization file.

  import { register as checkJob } from "./tools/check-job.js";
  import { register as searchMedia } from "./tools/search-media.js";
  import { register as listSearches } from "./tools/list-searches.js";
  import { register as detectAi } from "./tools/detect-ai.js";
  import { register as detectFingerprint } from "./tools/detect-fingerprint.js";
  import { register as detectMembership } from "./tools/detect-membership.js";
  import { register as registerMedia } from "./tools/register-media.js";
  import { register as listMedia } from "./tools/list-media.js";
  import { register as getMedia } from "./tools/get-media.js";
  import { register as updateMedia } from "./tools/update-media.js";
  import { register as deleteMedia } from "./tools/delete-media.js";
  import { register as getRights } from "./tools/get-rights.js";
  import { register as getBilling } from "./tools/get-billing.js";
  
  const apiKey = process.env.SDRM_API_KEY;
  if (!apiKey) {
    process.stderr.write(
      "Error: SDRM_API_KEY environment variable is required.\n" +
        "Get your API key at https://sdrm.io/api-keys\n",
    );
    process.exit(1);
  }
  
  const api = new ApiClient(apiKey, process.env.SDRM_BASE_URL);
  
  const server = new McpServer({
    name: "sdrm",
    version: "0.1.0",
  });
  
  // Discovery
  listAlgorithms(server, api);
  
  // Protection
  runAlgorithm(server, api);
  protectMedia(server, api);
  
  // Jobs
  checkJob(server, api);