mastodon_search

Instructions

Implementation Reference

• src/mastodon_tool.ts:250-307 (handler)

  Handler function that executes the mastodon_search tool: formats search parameters, calls MastodonClient.search, processes results into sections for accounts, hashtags, statuses, and returns formatted text content.

  async (params: SearchParams) => {
    const searchParams = {
      q: params.query,
      type: params.type,
      limit: params.limit,
      resolve: params.resolve,
      following: params.following,
    };
  
    const results = await client.search(searchParams);
    
    const sections = [];
    
    if (results.accounts.length > 0) {
      const accountsList = results.accounts.map((account, index) => {
        return `${index + 1}. @${account.acct} (${account.display_name})\n   Followers: ${account.followers_count} | Following: ${account.following_count} | Posts: ${account.statuses_count}\n   ${account.note.replace(/<[^>]*>/g, '').substring(0, 100)}...\n   URL: ${account.url}`;
      }).join('\n\n');
      sections.push(`**Accounts (${results.accounts.length})**\n${accountsList}`);
    }
    
    if (results.hashtags.length > 0) {
      const hashtagsList = results.hashtags.map((tag, index) => {
        const todayHistory = tag.history[0];
        const uses = todayHistory ? `${todayHistory.uses} uses` : "No recent data";
        return `${index + 1}. #${tag.name} (${uses})\n   URL: ${tag.url}`;
      }).join('\n\n');
      sections.push(`**Hashtags (${results.hashtags.length})**\n${hashtagsList}`);
    }
    
    if (results.statuses.length > 0) {
      const statusesList = results.statuses.map((post, index) => {
        const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : "";
        return `${index + 1}. @${post.account.acct}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n   Posted: ${new Date(post.created_at).toLocaleString()}\n   URL: ${post.url}`;
      }).join('\n\n');
      sections.push(`**Posts (${results.statuses.length})**\n${statusesList}`);
    }
    
    if (sections.length === 0) {
      return {
        content: [
          {
            type: "text",
            text: `No results found for query: "${params.query}"`
          }
        ],
      };
    }
    
    const summary = `Search results for "${params.query}"`;
    return {
      content: [
        {
          type: "text",
          text: `${summary}\n\n${sections.join('\n\n')}`,
        },
      ],
    };
  }

• src/mastodon_tool.ts:68-91 (schema)

  Zod input schema (SearchSchema) defining parameters for the mastodon_search tool: query, type, limit, resolve, following.

  const SearchSchema = z.object({
    query: z.string().describe("Search query text"),
    type: z
      .enum(["accounts", "hashtags", "statuses"])
      .describe("Type of content to search for")
      .optional(),
    limit: z
      .number()
      .min(1)
      .max(40)
      .describe("Number of results to return (1-40)")
      .default(20)
      .optional(),
    resolve: z
      .boolean()
      .describe("Whether to resolve non-local accounts/statuses")
      .default(false)
      .optional(),
    following: z
      .boolean()
      .describe("Only search accounts the user is following")
      .default(false)
      .optional(),
  });

• src/mastodon_tool.ts:246-308 (registration)

  Registration of the mastodon_search tool on the MCP server using server.tool, providing name, description, input schema, and handler function.

  server.tool(
    "mastodon_search",
    "Search for accounts, hashtags, or posts on Mastodon",
    SearchSchema.shape,
    async (params: SearchParams) => {
      const searchParams = {
        q: params.query,
        type: params.type,
        limit: params.limit,
        resolve: params.resolve,
        following: params.following,
      };
  
      const results = await client.search(searchParams);
      
      const sections = [];
      
      if (results.accounts.length > 0) {
        const accountsList = results.accounts.map((account, index) => {
          return `${index + 1}. @${account.acct} (${account.display_name})\n   Followers: ${account.followers_count} | Following: ${account.following_count} | Posts: ${account.statuses_count}\n   ${account.note.replace(/<[^>]*>/g, '').substring(0, 100)}...\n   URL: ${account.url}`;
        }).join('\n\n');
        sections.push(`**Accounts (${results.accounts.length})**\n${accountsList}`);
      }
      
      if (results.hashtags.length > 0) {
        const hashtagsList = results.hashtags.map((tag, index) => {
          const todayHistory = tag.history[0];
          const uses = todayHistory ? `${todayHistory.uses} uses` : "No recent data";
          return `${index + 1}. #${tag.name} (${uses})\n   URL: ${tag.url}`;
        }).join('\n\n');
        sections.push(`**Hashtags (${results.hashtags.length})**\n${hashtagsList}`);
      }
      
      if (results.statuses.length > 0) {
        const statusesList = results.statuses.map((post, index) => {
          const mediaInfo = post.media_attachments.length > 0 ? ` [${post.media_attachments.length} media]` : "";
          return `${index + 1}. @${post.account.acct}: ${post.content.replace(/<[^>]*>/g, '').substring(0, 100)}...${mediaInfo}\n   Posted: ${new Date(post.created_at).toLocaleString()}\n   URL: ${post.url}`;
        }).join('\n\n');
        sections.push(`**Posts (${results.statuses.length})**\n${statusesList}`);
      }
      
      if (sections.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No results found for query: "${params.query}"`
            }
          ],
        };
      }
      
      const summary = `Search results for "${params.query}"`;
      return {
        content: [
          {
            type: "text",
            text: `${summary}\n\n${sections.join('\n\n')}`,
          },
        ],
      };
    }
  );

• src/api.ts:152-155 (helper)

  MastodonClient.search helper method called by the tool handler to perform the actual API search request.

  async search(params: SearchParams): Promise<MastodonSearchResults> {
    const queryParams = this.buildQueryParams(params);
    return this.request<MastodonSearchResults>(`/api/v2/search${queryParams}`);
  }

• src/mastodon_types.ts:187-191 (schema)

  TypeScript interface defining the structure of search results returned by Mastodon API (used by client.search).

  export interface MastodonSearchResults {
    accounts: MastodonAccount[];
    statuses: MastodonStatus[];
    hashtags: MastodonTrendingTag[];
  }

• src/mcp-server.ts:13-14 (registration)

  Top-level call to addMastodonTool which registers all Mastodon tools including mastodon_search.

  // Add Mastodon tool to server
  await addMastodonTool(server);