Bluesky MCP Server

Instructions

Implementation Reference

• src/index.ts:387-409 (registration)

  Registration of the 'convert-url-to-uri' MCP tool, including description, input schema, and inline handler function that calls the helper.

    "convert-url-to-uri",
    "Convert a Bluesky web URL to an AT URI format that can be used with other tools",
    {
      url: z.string().describe("Bluesky post URL to convert (e.g., https://bsky.app/profile/username.bsky.social/post/postid)")
    },
    async ({ url }) => {
      if (!agent) {
        return mcpErrorResponse("Not logged in. Please check your environment variables.");
      }
  
      try {
        const atUri = await convertBskyUrlToAtUri(url, agent);
        
        if (!atUri) {
          return mcpErrorResponse(`Failed to convert URL: ${url}. Make sure it's a valid Bluesky post URL.`);
        }
        
        return mcpSuccessResponse(`Successfully converted to AT URI: ${atUri}`);
      } catch (error) {
        return mcpErrorResponse(`Error converting URL: ${error instanceof Error ? error.message : String(error)}`);
      }
    }
  );

• src/index.ts:392-408 (handler)

  Inline handler function for the 'convert-url-to-uri' tool that validates agent, calls convertBskyUrlToAtUri, and formats response.

  async ({ url }) => {
    if (!agent) {
      return mcpErrorResponse("Not logged in. Please check your environment variables.");
    }
  
    try {
      const atUri = await convertBskyUrlToAtUri(url, agent);
      
      if (!atUri) {
        return mcpErrorResponse(`Failed to convert URL: ${url}. Make sure it's a valid Bluesky post URL.`);
      }
      
      return mcpSuccessResponse(`Successfully converted to AT URI: ${atUri}`);
    } catch (error) {
      return mcpErrorResponse(`Error converting URL: ${error instanceof Error ? error.message : String(error)}`);
    }
  }

• src/index.ts:389-391 (schema)

  Input schema for the tool using Zod: requires a 'url' string parameter.

  {
    url: z.string().describe("Bluesky post URL to convert (e.g., https://bsky.app/profile/username.bsky.social/post/postid)")
  },

• src/utils.ts:257-276 (helper)

  Core helper function that parses the Bluesky URL, resolves handle to DID using agent, and constructs the AT URI.

  export async function convertBskyUrlToAtUri(url: string, agent: AtpAgent): Promise<string | null> {
    try {
      const parsed = parseBskyUrl(url);
      if (!parsed) return null;
      
      // Resolve the handle to a DID
      const resolveResponse = await agent.resolveHandle({ handle: parsed.handle });
      
      if (!resolveResponse.success) {
        return null;
      }
      
      const did = resolveResponse.data.did;
      
      // Construct the AT URI
      return `at://${did}/app.bsky.feed.post/${parsed.rkey}`;
    } catch (error) {
      return null;
    }
  }

• src/utils.ts:231-249 (helper)

  Supporting helper function to parse Bluesky web URL into handle and rkey components.

  export function parseBskyUrl(url: string): { handle: string, rkey: string } | null {
    try {
      // Remove any @ prefix if provided
      const cleanUrl = url.trim().replace(/^@/, '');
      
      // Match patterns like https://bsky.app/profile/username.bsky.social/post/postid
      const regex = /https?:\/\/bsky\.app\/profile\/([^\/]+)\/post\/([^\/\?#]+)/;
      const match = cleanUrl.match(regex);
      
      if (!match) return null;
      
      return {
        handle: match[1],
        rkey: match[2]
      };
    } catch (error) {
      return null;
    }
  }