MCP Snapshot Server

Instructions

Implementation Reference

• src/server.ts:158-171 (handler)

  MCP tool handler for 'getProposals': parses arguments using ProposalsParamsSchema, calls snapshotService.getProposals with spaceId, state, and limit, and returns the proposals as JSON text content.

  case "getProposals": {
    const parsedArgs = ProposalsParamsSchema.parse(args);
    const proposals = await this.snapshotService.getProposals(
      parsedArgs.spaceId,
      parsedArgs.state || "all",
      parsedArgs.limit || 20
    );
    return {
      content: [{
        type: "text",
        text: JSON.stringify(proposals, null, 2)
      }]
    };
  }

• src/server.ts:22-26 (schema)

  Zod schema (ProposalsParamsSchema) for input validation of getProposals tool: requires spaceId, optional state and limit.

  const ProposalsParamsSchema = z.object({
    spaceId: z.string(),
    state: z.string().optional(),
    limit: z.number().optional()
  });

• src/server.ts:80-92 (registration)

  Tool registration in listTools handler: defines 'getProposals' with description and inputSchema matching the Zod schema.

  {
    name: "getProposals",
    description: "Get proposals for a Snapshot space",
    inputSchema: {  // Changed from parameters to inputSchema
      type: "object",
      properties: {
        spaceId: { type: "string", description: "ID of the space" },
        state: { type: "string", description: "Filter by proposal state (active, closed, pending, all)" },
        limit: { type: "number", description: "Number of proposals to fetch" }
      },
      required: ["spaceId"]
    }
  },

• src/services/snapshotService.ts:223-255 (helper)

  Core implementation of getProposals in SnapshotService: constructs and executes GraphQL query to fetch proposals for a space, filtered by state if specified, returns Proposal[].

  async getProposals(spaceId: string, state: string = "all", first: number = 20): Promise<Proposal[]> {
    const query = `
      query Proposals {
        proposals (
          first: ${first},
          skip: 0,
          where: {
            space_in: ["${spaceId}"]
            ${state !== "all" ? `, state: "${state}"` : ''}
          },
          orderBy: "created",
          orderDirection: desc
        ) {
          id
          title
          body
          choices
          start
          end
          snapshot
          state
          author
          space {
            id
            name
          }
        }
      }
    `;
  
    const result = await this.queryGraphQL(query);
    return result.proposals;
  }

• src/services/snapshotService.ts:33-47 (schema)

  TypeScript interface Proposal defining the structure of proposal objects returned by getProposals.

  interface Proposal {
    id: string;
    title: string;
    body?: string;
    choices: string[];
    start: number;
    end: number;
    snapshot: string;
    state: string;
    author: string;
    space: {
      id: string;
      name: string;
    };
  }