ad4m_agent_status

Instructions

Implementation Reference

• src/index.ts:270-278 (handler)

  Core handler for 'ad4m_agent_status' tool. Executes a GraphQL query to the local AD4M executor to fetch agent status (isInitialized, isUnlocked, did) and returns the result formatted as MCP text content.

  // 1. ad4m_agent_status
  server.tool("ad4m_agent_status",
    "Get the local AD4M agent status: DID, initialization state, keystore lock state.",
    {},
    async () => {
      const data = await gql("{ agentStatus { isInitialized isUnlocked did } }");
      return ok(data.agentStatus);
    }
  );

• src/index.ts:271-273 (registration)

  Registration of the 'ad4m_agent_status' tool using McpServer.tool() with a description and empty input schema.

  server.tool("ad4m_agent_status",
    "Get the local AD4M agent status: DID, initialization state, keystore lock state.",
    {},

• src/index.ts:132-152 (helper)

  The gql() helper function that performs the actual GraphQL HTTP request to the AD4M executor, including error handling for connection refused and locked agent scenarios.

  async function gql(query: string, variables: Record<string, unknown> = {}): Promise<GqlResult> {
    const resp = await fetch(AD4M_GQL, {
      method:  "POST",
      headers: { "Content-Type": "application/json" },
      body:    JSON.stringify({ query, variables }),
      signal:  AbortSignal.timeout(10_000),
    });
    if (!resp.ok) throw new Error(`AD4M HTTP ${resp.status}: ${await resp.text()}`);
    const json = await resp.json() as { data?: GqlResult; errors?: { message: string }[] };
    if (json.errors?.length) {
      const msg = json.errors[0].message;
      if (msg.includes("ECONNREFUSED") || msg.includes("fetch failed")) {
        throw new Error("AD4M executor not reachable. Start it with: ad4m serve --port 4000");
      }
      if (msg.includes("Unauthorized") || msg.includes("not unlocked")) {
        throw new Error(`Agent is locked. Unlock with:\ncurl -X POST ${AD4M_GQL} -H 'Content-Type: application/json' -d '{"query":"mutation { agentUnlock(passphrase: \\"YOUR_PASSPHRASE\\") { isUnlocked } }"}'`);
      }
      throw new Error(msg);
    }
    return json.data ?? {};
  }

• src/index.ts:154-156 (helper)

  The ok() helper function that wraps the result data into MCP's expected { content: [{ type: 'text', text: ... }] } format.

  function ok(data: unknown) {
    return { content: [{ type: "text" as const, text: JSON.stringify(data, null, 2) }] };
  }

• index.js:516-519 (registration)

  Registration of 'ad4m_agent_status' in the compiled JS (ListToolsRequestSchema handler), defining name, description, and empty inputSchema.

    name: "ad4m_agent_status",
    description: "Get the local AD4M agent status: DID, initialization state, keystore lock state.",
    inputSchema: { type: "object", properties: {} },
  },