Sidearm MCP Server

Instructions

Implementation Reference

• src/tools/register-media.ts:35-61 (handler)

  The main handler function that executes the register_media tool. It processes the input parameters, constructs a request body, calls the API to register media at /api/v1/media endpoint, and returns the result formatted as MCP content.

  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.mode) body.mode = params.mode;
      if (params.expires_at) body.expires_at = params.expires_at;
      if (params.tags) body.tags = params.tags;
  
      const result = await api.post("/api/v1/media", body);
      return {
        content: [
          { type: "text" as const, text: JSON.stringify(result, null, 2) },
        ],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text" as const,
            text: `Error: ${err instanceof Error ? err.message : String(err)}`,
          },
        ],
        isError: true as const,
      };
    }
  },

• src/tools/register-media.ts:13-34 (schema)

  Zod schema definition for the register_media tool's input parameters, including optional fields for media_url (public URL), media (base64 content), mode (protection level: register/search_ready/standard/maximum), expires_at (ISO 8601 datetime), and tags (array of strings).

    media_url: z
      .string()
      .url()
      .optional()
      .describe("Public URL of the media to register"),
    media: z
      .string()
      .optional()
      .describe("Base64-encoded media content to register"),
    mode: z
      .enum(["register", "search_ready", "standard", "maximum"])
      .optional()
      .describe("Protection level. Default: standard"),
    expires_at: z
      .string()
      .optional()
      .describe("ISO 8601 datetime when this registration expires"),
    tags: z
      .array(z.string())
      .optional()
      .describe("Tags for organizing and filtering"),
  },

• src/tools/register-media.ts:5-63 (registration)

  The register function that defines and registers the register_media tool with the MCP server, including tool name, description, schema, and handler function.

  export function register(server: McpServer, api: ApiClient): void {
    server.tool(
      "register_media",
      "Register and protect media on the Sidearm platform. " +
        "Modes: register (provenance signing only), search_ready (register + vector indexing), " +
        "standard (search_ready + watermarks + AI-training poison), " +
        "maximum (standard + style cloaking + adversarial hardening). Returns the created media object.",
      {
        media_url: z
          .string()
          .url()
          .optional()
          .describe("Public URL of the media to register"),
        media: z
          .string()
          .optional()
          .describe("Base64-encoded media content to register"),
        mode: z
          .enum(["register", "search_ready", "standard", "maximum"])
          .optional()
          .describe("Protection level. Default: standard"),
        expires_at: z
          .string()
          .optional()
          .describe("ISO 8601 datetime when this registration expires"),
        tags: z
          .array(z.string())
          .optional()
          .describe("Tags for organizing and filtering"),
      },
      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.mode) body.mode = params.mode;
          if (params.expires_at) body.expires_at = params.expires_at;
          if (params.tags) body.tags = params.tags;
  
          const result = await api.post("/api/v1/media", body);
          return {
            content: [
              { type: "text" as const, text: JSON.stringify(result, null, 2) },
            ],
          };
        } catch (err) {
          return {
            content: [
              {
                type: "text" as const,
                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
              },
            ],
            isError: true as const,
          };
        }
      },
    );
  }

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

  Import statement for the register_media tool registration function from tools/register-media.js

  import { register as registerMedia } from "./tools/register-media.js";

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

  Call to register the register_media tool with the MCP server and API client

  registerMedia(server, api);