Anytype MCP Server

Instructions

Implementation Reference

• src/index.ts:441-477 (registration)

  Registration of the get_templates MCP tool with description, Zod input schema, and inline asynchronous handler function that proxies requests to the Anytype API endpoint `/spaces/{space_id}/types/{type_id}/templates`.

  this.server.tool(
    "get_templates",
    "Retrieves all available templates for a specific object type in an Anytype space. Templates provide pre-configured structures and content for creating new objects. This tool returns a list of templates with their IDs, names, and metadata. Results are paginated for types with many templates. Use this tool when you need to find appropriate templates for creating new objects of a specific type.",
    {
      space_id: z.string().describe("Space ID containing the type"),
      type_id: z.string().describe("Type ID to get templates for"),
      offset: z.number().optional().default(0).describe("Pagination offset"),
      limit: z
        .number()
        .optional()
        .default(100)
        .describe("Number of results per page (1-1000)"),
    },
    async ({ space_id, type_id, offset, limit }) => {
      try {
        // Validate limit
        const validLimit = Math.max(1, Math.min(1000, limit));
  
        const response = await this.makeRequest(
          "get",
          `/spaces/${space_id}/types/${type_id}/templates`,
          null,
          { offset, limit: validLimit }
        );
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify(response.data, null, 2),
            },
          ],
        };
      } catch (error) {
        return this.handleApiError(error);
      }
    }
  );

• src/index.ts:454-476 (handler)

  The core handler function for get_templates: validates pagination limit, performs authenticated GET request to Anytype API for templates of a type in a space, returns formatted JSON response or handles errors via shared helper.

  async ({ space_id, type_id, offset, limit }) => {
    try {
      // Validate limit
      const validLimit = Math.max(1, Math.min(1000, limit));
  
      const response = await this.makeRequest(
        "get",
        `/spaces/${space_id}/types/${type_id}/templates`,
        null,
        { offset, limit: validLimit }
      );
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify(response.data, null, 2),
          },
        ],
      };
    } catch (error) {
      return this.handleApiError(error);
    }
  }

• src/index.ts:444-453 (schema)

  Zod schema defining input parameters for get_templates tool: required space_id and type_id strings, optional offset (default 0) and limit (default 100, clamped 1-1000) numbers for pagination.

  {
    space_id: z.string().describe("Space ID containing the type"),
    type_id: z.string().describe("Type ID to get templates for"),
    offset: z.number().optional().default(0).describe("Pagination offset"),
    limit: z
      .number()
      .optional()
      .default(100)
      .describe("Number of results per page (1-1000)"),
  },

• src/index.ts:915-938 (helper)

  Shared helper method used by get_templates (and other tools) to make authenticated HTTP requests to Anytype API using axios, with Bearer token from env var.

  private async makeRequest(
    method: "get" | "post" | "delete",
    endpoint: string,
    data?: any,
    params?: any
  ) {
    try {
      const config = {
        method,
        url: `${this.apiBaseUrl}${endpoint}`,
        headers: {
          Authorization: `Bearer ${this.appKey}`,
          "Content-Type": "application/json",
        },
        data,
        params,
      };
  
      return await axios(config);
    } catch (error) {
      console.error(`API request error: ${error}`);
      throw error;
    }
  }

• src/index.ts:989-1050 (helper)

  Shared error handling helper invoked by get_templates handler to format and return standardized error responses for API failures, network issues, and HTTP status codes.

  private handleApiError(error: any) {
    let errorMessage = "Unknown API error";
  
    // Handle network errors first
    if (error.code === "ECONNREFUSED") {
      errorMessage = "Anytype is not running. Launch it and try again.";
      return this.printError(error, errorMessage);
    }
  
    // Handle API response errors
    const status = error.response?.status;
    const apiError = error.response?.data?.error;
  
    switch (status) {
      case 400:
        errorMessage = apiError?.message || "Bad request";
        if (apiError?.code === "validation_error") {
          errorMessage +=
            ". Invalid parameters: " +
            (apiError.details
              ?.map((d: { field: string }) => d.field)
              .join(", ") || "unknown fields");
        }
        break;
      case 401:
        errorMessage = "Unauthorized - Check your App Key";
        break;
      case 403:
        errorMessage =
          "Forbidden - You don't have permission for this operation";
        break;
      case 404:
        errorMessage = "Not found - The requested resource doesn't exist";
        break;
      case 429:
        errorMessage = "Rate limit exceeded - Try again later";
        break;
      case 500:
        errorMessage = "Internal server error - Contact Anytype support";
        break;
      default:
        if (status >= 500 && status < 600) {
          errorMessage = `Server error (${status}) - Try again later`;
        } else if (apiError?.message) {
          errorMessage = apiError.message;
        }
        break;
    }
    return this.printError(apiError, errorMessage);
  }
  
  private printError(error: any, errorMessage: any) {
    return {
      content: [
        {
          type: "text" as const,
          text: `Error: ${errorMessage}\n\n${error}`,
        },
      ],
      isError: true,
    };
  }