Sidearm MCP Server

Instructions

Implementation Reference

• src/tools/protect-media.ts:5-90 (handler)

  Main handler function that registers the protect_media tool with MCP server, defines the input schema, and implements the execution logic that calls the SDRM API /api/v1/protect endpoint with media data and protection level.

  export function register(server: McpServer, api: ApiClient): void {
    server.tool(
      "protect_media",
      "Protect media using a curated preset level. Automatically selects the best " +
        "combination of algorithms for the given media type. Simpler than run_algorithm — " +
        "just specify standard or maximum protection. Provide either a public media_url, " +
        "base64 media, or text content. Returns a job_id — use check_job to poll for results.",
      {
        media_url: z
          .string()
          .url()
          .optional()
          .describe("Public URL of the media file to protect"),
        media: z
          .string()
          .optional()
          .describe("Base64-encoded media content (alternative to media_url)"),
        text: z
          .string()
          .optional()
          .describe("Plain text content to protect"),
        mime: z
          .string()
          .optional()
          .describe("MIME type (e.g. image/png, audio/wav, text/plain)"),
        level: z
          .enum(["standard", "maximum"])
          .optional()
          .describe(
            "Protection level: standard (fast, good protection) or maximum (slower, strongest protection). Default: standard",
          ),
        tags: z
          .array(z.string())
          .optional()
          .describe("Tags for organizing and filtering"),
        webhook_url: z
          .string()
          .url()
          .optional()
          .describe("URL to receive a POST when the job completes"),
        filename: z
          .string()
          .optional()
          .describe("Original filename for human-readable output naming"),
      },
      async (params) => {
        try {
          const body: Record<string, unknown> = {};
          if (params.media_url) body.media_url = params.media_url;
          if (params.media) body.media = params.media;
          if (params.text) body.text = params.text;
          if (params.mime) body.mime = params.mime;
          if (params.level) body.level = params.level;
          if (params.tags) body.tags = params.tags;
          if (params.webhook_url) body.webhook_url = params.webhook_url;
          if (params.filename) body.filename = params.filename;
  
          const result = await api.post("/api/v1/protect", body);
          const res = result as { job_id: string; status_url: string };
  
          return {
            content: [
              {
                type: "text" as const,
                text:
                  `Protection job created.\n\n` +
                  `Job ID: ${res.job_id}\n` +
                  `Status URL: ${res.status_url}\n\n` +
                  `Use check_job with this job_id to poll for results.`,
              },
            ],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
              },
            ],
            isError: true as const,
          };
        }
      },
    );
  }

• src/tools/protect-media.ts:12-49 (schema)

  Zod schema defining the input parameters for protect_media: media_url, media (base64), text, mime type, protection level (standard/maximum), tags, webhook_url, and filename.

  {
    media_url: z
      .string()
      .url()
      .optional()
      .describe("Public URL of the media file to protect"),
    media: z
      .string()
      .optional()
      .describe("Base64-encoded media content (alternative to media_url)"),
    text: z
      .string()
      .optional()
      .describe("Plain text content to protect"),
    mime: z
      .string()
      .optional()
      .describe("MIME type (e.g. image/png, audio/wav, text/plain)"),
    level: z
      .enum(["standard", "maximum"])
      .optional()
      .describe(
        "Protection level: standard (fast, good protection) or maximum (slower, strongest protection). Default: standard",
      ),
    tags: z
      .array(z.string())
      .optional()
      .describe("Tags for organizing and filtering"),
    webhook_url: z
      .string()
      .url()
      .optional()
      .describe("URL to receive a POST when the job completes"),
    filename: z
      .string()
      .optional()
      .describe("Original filename for human-readable output naming"),
  },

• src/index.ts:8-44 (registration)

  Import and registration of protect_media tool in the main server initialization - imported at line 8 and registered at line 44 with the MCP server and API client instances.

  import { register as protectMedia } from "./tools/protect-media.js";
  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);

• src/tools/protect-media.ts:50-88 (handler)

  Core execution logic that builds the request body from parameters, calls api.post('/api/v1/protect'), and returns formatted response with job_id and status_url or error message.

  async (params) => {
    try {
      const body: Record<string, unknown> = {};
      if (params.media_url) body.media_url = params.media_url;
      if (params.media) body.media = params.media;
      if (params.text) body.text = params.text;
      if (params.mime) body.mime = params.mime;
      if (params.level) body.level = params.level;
      if (params.tags) body.tags = params.tags;
      if (params.webhook_url) body.webhook_url = params.webhook_url;
      if (params.filename) body.filename = params.filename;
  
      const result = await api.post("/api/v1/protect", body);
      const res = result as { job_id: string; status_url: string };
  
      return {
        content: [
          {
            type: "text" as const,
            text:
              `Protection job created.\n\n` +
              `Job ID: ${res.job_id}\n` +
              `Status URL: ${res.status_url}\n\n` +
              `Use check_job with this job_id to poll for results.`,
          },
        ],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
          },
        ],
        isError: true as const,
      };
    }
  },

• src/api.ts:25-31 (helper)

  ApiClient.post method used by protect_media handler to make HTTP POST requests to the SDRM API with authentication headers.

  async post<T = unknown>(path: string, body: unknown): Promise<T> {
    return this.request<T>(new URL(`${this.baseUrl}${path}`), {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(body),
    });
  }