MCP Snapshot Server

Instructions

Implementation Reference

• src/services/snapshotService.ts:298-435 (handler)

  Core handler function that performs the GraphQL query to retrieve ranked Snapshot spaces based on first, skip, category, and optional search parameters.

  async getRankedSpaces(
    first: number = 18, 
    skip: number = 0, 
    category: string = "all",
    search?: string
  ): Promise<RankedSpace[]> {
    const query = `
      query ($first: Int, $skip: Int, $where: RankingWhere) {
        ranking(first: $first, skip: $skip, where: $where) {
          items {
            id
            verified
            turbo
            admins
            members
            name
            avatar
            cover
            network
            about
            website
            twitter
            github
            coingecko
            symbol
            activeProposals
            treasuries {
              name
              network
              address
            }
            labels {
              id
              name
              description
              color
            }
            delegationPortal {
              delegationType
              delegationContract
              delegationNetwork
              delegationApi
            }
            voting {
              delay
              period
              type
              quorum
              quorumType
              privacy
              hideAbstain
            }
            strategies {
              name
              params
              network
            }
            validation {
              name
              params
            }
            filters {
              minScore
              onlyMembers
            }
            proposalsCount
            proposalsCount1d
            proposalsCount30d
            votesCount
            followersCount
            children {
              id
              name
              avatar
              cover
              proposalsCount
              votesCount
              activeProposals
              turbo
              verified
              network
            }
            parent {
              id
              name
              avatar
              cover
              proposalsCount
              votesCount
              activeProposals
              turbo
              verified
              network
            }
            terms
            private
            domain
            skin
            skinSettings {
              bg_color
              link_color
              text_color
              content_color
              border_color
              heading_color
              primary_color
              theme
            }
            guidelines
            template
            categories
            moderators
            plugins
            boost {
              enabled
              bribeEnabled
            }
            voteValidation {
              name
              params
            }
          }
        }
      }
    `;
  
    const variables = {
      first,
      skip,
      where: {
        category,
        ...(search ? { search } : {})
      }
    };
  
    const result = await this.queryGraphQL(query, variables);
    return result.ranking.items;
  }

• src/server.ts:36-41 (schema)

  Zod schema used for input parameter validation in the getRankedSpaces tool call handler.

  const RankedSpacesParamsSchema = z.object({
    first: z.number().optional(),
    skip: z.number().optional(),
    category: z.string().optional(),
    search: z.string().optional()
  });

• src/server.ts:115-127 (registration)

  Tool registration entry in the ListTools response, defining name, description, and input schema for MCP protocol.

  {
    name: "getRankedSpaces",
    description: "Get ranked list of Snapshot spaces with detailed information",
    inputSchema: {
      type: "object",
      properties: {
        first: { type: "number", description: "Number of spaces to fetch (default: 18)" },
        skip: { type: "number", description: "Number of spaces to skip (default: 0)" },
        category: { type: "string", description: "Category to filter by (default: 'all')" },
        search: { type: "string", description: "Search term to filter spaces" }
      }
    }
  }

• src/server.ts:192-206 (handler)

  Dispatch handler in the tool call switch statement that validates args, calls the snapshotService, and formats response.

  case "getRankedSpaces": {
    const parsedArgs = RankedSpacesParamsSchema.parse(args);
    const spaces = await this.snapshotService.getRankedSpaces(
      parsedArgs.first || 18,
      parsedArgs.skip || 0,
      parsedArgs.category || "all",
      parsedArgs.search
    );
    return {
      content: [{
        type: "text",
        text: JSON.stringify(spaces, null, 2)
      }]
    };
  }

• src/services/snapshotService.ts:56-168 (schema)

  Type definition for the RankedSpace object returned by the GraphQL query in the handler.

  interface RankedSpace {
    id: string;
    verified: boolean;
    turbo: boolean;
    admins: string[];
    members: string[];
    name: string;
    avatar: string;
    cover: string;
    network: string;
    about: string;
    website?: string;
    twitter?: string;
    github?: string;
    coingecko?: string;
    symbol: string;
    activeProposals: number;
    treasuries: {
      name: string;
      network: string;
      address: string;
    }[];
    voting: {
      delay: number;
      period: number;
      type: string;
      quorum: number;
      quorumType: string;
      privacy: string;
      hideAbstain: boolean;
    };
    proposalsCount: number;
    votesCount: number;
    followersCount: number;
    labels: {
      id: string;
      name: string;
      description: string;
      color: string;
    }[];
    delegationPortal: {
      delegationType: string;
      delegationContract: string;
      delegationNetwork: string;
      delegationApi: string;
    };
    strategies: {
      name: string;
      params: any;
      network: string;
    }[];
    validation: {
      name: string;
      params: any;
    };
    filters: {
      minScore: number;
      onlyMembers: boolean;
    };
    proposalsCount1d: number;
    proposalsCount30d: number;
    children: {
      id: string;
      name: string;
      avatar: string;
      cover: string;
      proposalsCount: number;
      votesCount: number;
      activeProposals: number;
      turbo: boolean;
      verified: boolean;
      network: string;
    }[];
    parent: {
      id: string;
      name: string;
      avatar: string;
      cover: string;
      proposalsCount: number;
      votesCount: number;
      activeProposals: number;
      turbo: boolean;
      verified: boolean;
      network: string;
    };
    terms: string;
    private: boolean;
    domain: string;
    skin: string;
    skinSettings: {
      bg_color: string;
      link_color: string;
      text_color: string;
      content_color: string;
      border_color: string;
      heading_color: string;
      primary_color: string;
      theme: string;
    };
    guidelines: string;
    template: string;
    categories: string[];
    moderators: string[];
    plugins: any;
    boost: {
      enabled: boolean;
      bribeEnabled: boolean;
    };
    voteValidation: {
      name: string;
      params: any;
    };
  }