dao-proposals-mcp

Instructions

Fetch a list of recent proposals for a given Snapshot space.

Parameters:
    space_id (str): The unique identifier of the Snapshot space (e.g., 'ens.eth').

Returns:
    A formatted string containing details of up to 10 recent proposals.

Implementation Reference

• main.py:60-106 (handler)

  The core handler function that executes the tool logic: queries the Snapshot GraphQL API for the 10 most recent proposals in the given space_id, formats their details using ts2str helper, and returns a string summary.

  async def list_proposals(space_id: str, ctx: Context) -> str:
      """
      Fetch a list of recent proposals for a given Snapshot space.
      
      Parameters:
          space_id (str): The unique identifier of the Snapshot space (e.g., 'ens.eth').
      
      Returns:
          A formatted string containing details of up to 10 recent proposals.
      """
      query = """
      query Proposals($space: String!) {
        proposals(first: 10, orderBy: "created", orderDirection: desc, where: { space: $space }) {
          id
          title
          state
          created
          end
        }
      }
      """
      async with httpx.AsyncClient() as client:
          try:
              response = await client.post(
                  SNAPSHOT_API,
                  json={"query": query, "variables": {"space": space_id}}
              )
              response.raise_for_status()
              data = response.json()
              proposals = data.get("data", {}).get("proposals", [])
              
              # Format proposals as a readable string
              result = []
              for i, proposal in enumerate(proposals):
                  created_str = ts2str(proposal['created'])
                  end_str = ts2str(proposal['end'])
                  result.append(
                      f"Proposal ID: {proposal['id']}\n"
                      f"Title: {proposal['title']}\n"
                      f"State: {proposal['state']}\n"
                      f"Created: {created_str}\n"
                      f"End: {end_str}\n"
                      "---"
                  )
              return "\n".join(result) if result else "No proposals found"
          except Exception as e:
              return f"Error: {str(e)}"

• main.py:59-59 (registration)

  The @mcp.tool() decorator from FastMCP registers the list_proposals function as an available MCP tool.

  @mcp.tool()

• main.py:61-69 (schema)

  Docstring providing schema details: input parameter space_id (str), output str with formatted proposal list. Type hints reinforce this.

  """
  Fetch a list of recent proposals for a given Snapshot space.
  
  Parameters:
      space_id (str): The unique identifier of the Snapshot space (e.g., 'ens.eth').
  
  Returns:
      A formatted string containing details of up to 10 recent proposals.
  """

• main.py:13-15 (helper)

  Supporting utility function to convert Unix timestamps from the API into human-readable datetime strings, used in the proposal formatting.

  def ts2str(ts: int) -> str:
    dt = datetime.fromtimestamp(ts)
    return dt.strftime("%Y-%m-%d %H:%M:%S")