twitterapi-docs-mcp

Instructions

Implementation Reference

• index.js:1294-1348 (handler)

  Handler function that implements the list_twitterapi_endpoints tool logic. Loads documentation data, categorizes endpoints based on keywords in their names, and generates a markdown-formatted list of endpoints grouped by category (user, tweet, etc.) or filtered by a specific category.

      case "list_twitterapi_endpoints": {
        // Validate category (optional)
        const validation = validateCategory(args.category);
        if (!validation.valid) {
          return formatToolError(validation.error);
        }
  
        const endpoints = Object.entries(data.endpoints || {});
  
        const categories = {
          user: [], tweet: [], list: [], community: [], trend: [],
          dm: [], action: [], webhook: [], stream: [], other: [],
        };
  
        for (const [name, ep] of endpoints) {
          if (name.includes("user") || name.includes("follow")) {
            categories.user.push({ name, ...ep });
          } else if (name.includes("tweet") || name.includes("search") || name.includes("article")) {
            categories.tweet.push({ name, ...ep });
          } else if (name.includes("list")) {
            categories.list.push({ name, ...ep });
          } else if (name.includes("community")) {
            categories.community.push({ name, ...ep });
          } else if (name.includes("trend")) {
            categories.trend.push({ name, ...ep });
          } else if (name.includes("dm")) {
            categories.dm.push({ name, ...ep });
          } else if (name.includes("webhook") || name.includes("rule")) {
            categories.webhook.push({ name, ...ep });
          } else if (name.includes("monitor") || name.includes("stream")) {
            categories.stream.push({ name, ...ep });
          } else if (["login", "like", "retweet", "create", "delete", "upload"].some(k => name.includes(k))) {
            categories.action.push({ name, ...ep });
          } else {
            categories.other.push({ name, ...ep });
          }
        }
  
        if (validation.value && categories[validation.value]) {
          const filtered = categories[validation.value];
          return formatToolSuccess(`## ${validation.value.toUpperCase()} Endpoints (${filtered.length})
  
  ${filtered.map((e) => `- **${e.name}**: ${e.method || "GET"} ${e.path || ""}\n  ${e.description || ""}`).join("\n\n")}`);
        }
  
        let output = `# TwitterAPI.io Endpoints (Total: ${endpoints.length})\n\n`;
        for (const [cat, eps] of Object.entries(categories)) {
          if (eps.length > 0) {
            output += `## ${cat.toUpperCase()} (${eps.length})\n`;
            output += eps.map((e) => `- **${e.name}**: ${e.method || "GET"} ${e.path || ""}`).join("\n");
            output += "\n\n";
          }
        }
        return formatToolSuccess(output);
      }

• index.js:986-1022 (registration)

  Tool registration in the MCP server's ListToolsRequestSchema handler, including name, description, input schema (optional category filter), and output schema.

      {
        name: "list_twitterapi_endpoints",
        description: `List all TwitterAPI.io API endpoints organized by category.
  
  USE THIS WHEN: You need to browse available endpoints or find endpoints by category.
  CATEGORIES: user, tweet, community, webhook, stream, action, dm, list, trend
  
  RETURNS: Endpoint names with HTTP method and path for each category.`,
        inputSchema: {
          type: "object",
          properties: {
            category: {
              type: "string",
              description: "Optional filter: user, tweet, community, webhook, stream, action, dm, list, trend",
              enum: ["user", "tweet", "community", "webhook", "stream", "action", "dm", "list", "trend"]
            },
          },
        },
        outputSchema: {
          type: "object",
          properties: {
            content: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  type: { type: "string", enum: ["text"] },
                  text: {
                    type: "string",
                    description: "Markdown list organized by category (USER, TWEET, WEBHOOK, etc.) with endpoint format: name: METHOD /path"
                  }
                }
              }
            }
          }
        }
      },

• index.js:576-596 (schema)

  Input validation helper function for the category parameter used in list_twitterapi_endpoints.

  function validateCategory(category) {
    if (!category) {
      return { valid: true, value: null }; // Optional parameter
    }
  
    const trimmed = category.trim().toLowerCase();
  
    if (!VALIDATION.CATEGORIES.includes(trimmed)) {
      return {
        valid: false,
        error: {
          type: ErrorType.INPUT_VALIDATION,
          message: `Unknown category: "${trimmed}"`,
          suggestion: `Available categories: ${VALIDATION.CATEGORIES.join(', ')}`,
          retryable: false
        }
      };
    }
  
    return { valid: true, value: trimmed };
  }

• index.js:471-471 (helper)

  VALIDATION constant defining allowed categories for filtering endpoints.

  CATEGORIES: ['user', 'tweet', 'community', 'webhook', 'stream', 'action', 'dm', 'list', 'trend', 'other']