Related Identity MCP Server

Instructions

Implementation Reference

• src/index.ts:245-286 (handler)

  The main handler function for the 'get-related-address' tool. It validates and normalizes the input platform and identity, executes a GraphQL query to fetch related identities and addresses, formats the response, and handles errors appropriately.

  async ({ platform, identity }) => {
    try {
      // Input validation and sanitization
      const normalizedPlatform = platform.toLowerCase().trim();
      const normalizedIdentity = identity.trim();
  
      if (!normalizedIdentity) {
        throw new Error("Identity cannot be empty");
      }
  
      // Execute GraphQL query
      const data = await executeGraphQLQuery({
        query: IDENTITY_QUERY,
        variables: {
          platform: normalizedPlatform,
          identity: normalizedIdentity,
        },
      });
  
      return {
        content: [
          {
            type: "text",
            text: `The related information is: ${JSON.stringify(data)}`,
          },
        ],
      };
    } catch (err) {
      const error = err as Error;
      console.error(`Error in get-related-address: ${error.message}`);
  
      return {
        content: [
          {
            type: "text",
            text: `Error fetching data: ${error.message}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/index.ts:239-244 (schema)

  Input schema definition for the tool parameters: platform (enum or string) and identity (string). Uses Zod for validation.

  {
    platform: PlatformSchema.describe(
      "The platform of a specific identity, e.g.: Ethereum, Farcaster, lens, ens"
    ),
    identity: IdentitySchema.describe("User's identity"),
  },

• src/index.ts:236-287 (registration)

  Full registration of the 'get-related-address' tool on the MCP server, including name, description, input schema, and inline handler function.

  server.tool(
    "get-related-address",
    "Retrieves all related identities associated with a specific platform identity. This tool helps discover cross-platform connections for the same person or entity. Use cases include: 1) Finding all accounts (Lens, Farcaster, ENS, etc.) belonging to the same person, 2) Resolving domain names to their underlying addresses (ENS domains, Lens handles, etc.)",
    {
      platform: PlatformSchema.describe(
        "The platform of a specific identity, e.g.: Ethereum, Farcaster, lens, ens"
      ),
      identity: IdentitySchema.describe("User's identity"),
    },
    async ({ platform, identity }) => {
      try {
        // Input validation and sanitization
        const normalizedPlatform = platform.toLowerCase().trim();
        const normalizedIdentity = identity.trim();
  
        if (!normalizedIdentity) {
          throw new Error("Identity cannot be empty");
        }
  
        // Execute GraphQL query
        const data = await executeGraphQLQuery({
          query: IDENTITY_QUERY,
          variables: {
            platform: normalizedPlatform,
            identity: normalizedIdentity,
          },
        });
  
        return {
          content: [
            {
              type: "text",
              text: `The related information is: ${JSON.stringify(data)}`,
            },
          ],
        };
      } catch (err) {
        const error = err as Error;
        console.error(`Error in get-related-address: ${error.message}`);
  
        return {
          content: [
            {
              type: "text",
              text: `Error fetching data: ${error.message}`,
            },
          ],
          isError: true,
        };
      }
    }
  );

• src/index.ts:199-229 (helper)

  Helper function to execute GraphQL queries against the web3.bio API with timeout, auth, and error handling. Used by the tool handler.

  async function executeGraphQLQuery(query: GraphQLQuery): Promise<any> {
    const response = await fetchWithTimeout(
      API_ENDPOINT,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "User-Agent": "relate-account-mcp/3.0.0",
          ...(process.env.ACCESS_TOKEN && {
            Authorization: process.env.ACCESS_TOKEN,
          }),
        },
        body: JSON.stringify(query),
      },
      REQUEST_TIMEOUT
    );
  
    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }
  
    const json = await response.json();
  
    if (json.errors) {
      throw new Error(
        `GraphQL errors: ${json.errors.map((e: any) => e.message).join(", ")}`
      );
    }
  
    return json.data;
  }

• src/index.ts:19-98 (helper)

  GraphQL query template for fetching identity details including resolved addresses, owner/manager addresses, profiles, and full identity graph connections.

  const IDENTITY_QUERY = `
    query QUERY_PROFILE($platform: Platform!, $identity: String!) {
      identity(platform: $platform, identity: $identity) {
        id
        status
        aliases
        identity
        platform
        network
        isPrimary
        primaryName
        resolvedAddress {
          address
          network
        }
        ownerAddress {
          address
          network
        }
        managerAddress {
          address
          network
        }
        updatedAt
        profile {
          identity
          platform
          network
          address
          displayName
          avatar
          description
          addresses {
            address
            network
          }
        }
        identityGraph {
          graphId
          vertices {
            identity
            platform
            network
            isPrimary
            primaryName
            registeredAt
            managerAddress {
              address
              network
            }
            ownerAddress {
              address
              network
            }
            resolvedAddress {
              address
              network
            }
            updatedAt
            expiredAt
            profile {
              uid
              identity
              platform
              network
              address
              displayName
              avatar
              description
              texts
              addresses {
                address
                network
              }
            }
          }
        }
      }
    }
  `;