Merge pull request #35 from chainapsis/fix/keplr-api-key-auto-resolve

fix: auto-resolve API key for keplr_api_* tools and prevent URL hallucination

Author: kws1207

packages/server/src/__tests__/tools/keplr-rpc.test.ts

@@ -27,6 +27,11 @@ vi.mock("node:os", async (importOriginal) => {
   return { ...actual, homedir: vi.fn(actual.homedir) };
 });
 
+const mockGetRpcResolver = vi.fn();
+vi.mock("../../rpc/resolver.js", () => ({
+  getRpcResolver: (...args: unknown[]) => mockGetRpcResolver(...args),
+}));
+
 // Dynamic import to avoid hoisting issues
 let keplrRpcPlugin: typeof import("../../plugins/keplr-rpc.js").default;
 
@@ -60,6 +65,8 @@ beforeEach(async () => {
     storePendingAction: vi.fn().mockReturnValue("mock-confirmation-token"),
   } as never);
   mockFetch.mockReset();
+  // Default: no API key configured in resolver
+  mockGetRpcResolver.mockReturnValue({ apiKey: undefined, hasApiKey: false });
   await keplrRpcPlugin.register(server as never, store as never);
 });
 
@@ -644,3 +651,55 @@ describe("HTTP error mapping", () => {
     );
   });
 });
+
+// ─── API key auto-resolution ───────────────────────────────────────
+describe("API key auto-resolution", () => {
+  it("should auto-detect API key from resolver when not provided", async () => {
+    mockGetRpcResolver.mockReturnValue({
+      apiKey: "keplr_from_env",
+      hasApiKey: true,
+    });
+    mockFetch.mockResolvedValueOnce(
+      okJson({ balance: 1000000, usage: { last7Days: {}, byChain: [] } }),
+    );
+
+    const tool = server.getTool("keplr_api_get_usage_summary")!;
+    const result = await tool.handler({});
+    const parsed = parseToolResponse(result);
+    expect(parsed).toHaveProperty("balance", 1000000);
+
+    // Verify the resolved key was used in the fetch URL
+    const fetchUrl = mockFetch.mock.calls[0][0] as string;
+    expect(fetchUrl).toContain("keplr_from_env");
+  });
+
+  it("should prefer explicit API key over configured key", async () => {
+    mockGetRpcResolver.mockReturnValue({
+      apiKey: "keplr_from_env",
+      hasApiKey: true,
+    });
+    mockFetch.mockResolvedValueOnce(
+      okJson({ balance: 500000, usage: { last7Days: {}, byChain: [] } }),
+    );
+
+    const tool = server.getTool("keplr_api_get_usage_summary")!;
+    const result = await tool.handler({ apiKey: "keplr_explicit" });
+    const parsed = parseToolResponse(result);
+    expect(parsed).toHaveProperty("balance", 500000);
+
+    const fetchUrl = mockFetch.mock.calls[0][0] as string;
+    expect(fetchUrl).toContain("keplr_explicit");
+    expect(fetchUrl).not.toContain("keplr_from_env");
+  });
+
+  it("should return setup guide when no API key is available", async () => {
+    mockGetRpcResolver.mockReturnValue({ apiKey: undefined, hasApiKey: false });
+
+    const tool = server.getTool("keplr_api_get_usage_summary")!;
+    const result = await tool.handler({});
+    const parsed = parseToolResponse(result);
+    expect(parsed).toHaveProperty("status", "setup_required");
+    expect(parsed).toHaveProperty("setupGuide");
+    expect(mockFetch).not.toHaveBeenCalled();
+  });
+});

packages/server/src/index.ts

@@ -34,7 +34,9 @@ const server = new McpServer(
       "Before executing any wallet tool for the first time in a session, call `onboarding-status` to check setup progress and guide the user through any remaining steps.\n\n" +
       "IMPORTANT: Do NOT guess Cosmos chain IDs — they are often non-obvious " +
       "(e.g., 'nyx' for Nym, 'phoenix-1' for Terra, 'columbus-5' for Terra Classic). " +
-      "Always call list-cosmos-chains to verify the correct chain ID before using any chain-dependent tool.",
+      "Always call list-cosmos-chains to verify the correct chain ID before using any chain-dependent tool.\n\n" +
+      "IMPORTANT: The Keplr API key dashboard is at https://api.keplr.app — NEVER guess or infer URLs for Keplr services. " +
+      "If asked where to get an API key, always direct users to https://api.keplr.app",
   },
 );
 

packages/server/src/plugins/keplr-rpc.ts

@@ -2,6 +2,7 @@ import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { z } from "zod";
 import type { SuggestedAction } from "../errors.js";
 import { classifyError, formatClassifiedError } from "../errors.js";
+import { getRpcResolver } from "../rpc/resolver.js";
 import type { KeplrPlugin } from "./types.js";
 
 // ─── HTTP Client ─────────────────────────────────────────────────────
@@ -193,17 +194,28 @@ const keplrRpcPlugin: KeplrPlugin = {
   name: "keplr-rpc",
 
   register(server, _store) {
+    /** Resolve API key: explicit param → configured key (env / config file). */
+    const resolveApiKey = (explicit?: string): string => {
+      const key = explicit || getRpcResolver().apiKey;
+      if (!key) {
+        throw new KeplrApiError(403, "No API key configured");
+      }
+      return key;
+    };
+
     // ── keplr_api_configure_key ────────────────────────────────────────
     server.registerTool(
       "keplr_api_configure_key",
       {
         description:
-          "Configure a Keplr Infra API key. Validates the key, then saves it to the MCP configuration file " +
+          "Configure a Keplr Infra API key (get one at https://api.keplr.app). Validates the key, then saves it to the MCP configuration file " +
           "based on the detected client. Restart required after configuration.",
         inputSchema: {
           apiKey: z
             .string()
-            .describe("Keplr Infra API key (starts with 'keplr_')"),
+            .describe(
+              "Keplr Infra API key from https://api.keplr.app (starts with 'keplr_')",
+            ),
           scope: z
             .enum(["user", "project"])
             .optional()
@@ -482,12 +494,18 @@ const keplrRpcPlugin: KeplrPlugin = {
       {
         description: "Validate an existing Keplr Infra API key",
         inputSchema: {
-          apiKey: z.string().describe("API key to validate"),
+          apiKey: z
+            .string()
+            .optional()
+            .describe(
+              "API key to validate (auto-detected from configured key if omitted)",
+            ),
         },
         annotations: { readOnlyHint: true },
       },
-      async ({ apiKey }) => {
+      async ({ apiKey: explicitKey }) => {
         try {
+          const apiKey = resolveApiKey(explicitKey);
           const data = await keplrApiFetch<Record<string, unknown>>({
             method: "POST",
             path: "/v1/keys/validate",
@@ -536,12 +554,16 @@ const keplrRpcPlugin: KeplrPlugin = {
       {
         description: "Get a Stripe payment link to add credits",
         inputSchema: {
-          apiKey: z.string().describe("API key"),
+          apiKey: z
+            .string()
+            .optional()
+            .describe("API key (auto-detected from configured key if omitted)"),
         },
         annotations: { readOnlyHint: true },
       },
-      async ({ apiKey }) => {
+      async ({ apiKey: explicitKey }) => {
         try {
+          const apiKey = resolveApiKey(explicitKey);
           const data = await keplrApiFetch<Record<string, unknown>>({
             method: "GET",
             path: "/v1/credits/payment-link",
@@ -582,12 +604,16 @@ const keplrRpcPlugin: KeplrPlugin = {
         description:
           "Get usage summary (balance, requests, credits, per-chain breakdown)",
         inputSchema: {
-          apiKey: z.string().describe("API key"),
+          apiKey: z
+            .string()
+            .optional()
+            .describe("API key (auto-detected from configured key if omitted)"),
         },
         annotations: { readOnlyHint: true },
       },
-      async ({ apiKey }) => {
+      async ({ apiKey: explicitKey }) => {
         try {
+          const apiKey = resolveApiKey(explicitKey);
           const raw = await keplrApiFetch<Record<string, unknown>>({
             method: "GET",
             path: `/v1/usage/${apiKey}/summary`,
@@ -633,7 +659,10 @@ const keplrRpcPlugin: KeplrPlugin = {
         description:
           "Get usage history with optional date/chain/endpoint filters",
         inputSchema: {
-          apiKey: z.string().describe("API key"),
+          apiKey: z
+            .string()
+            .optional()
+            .describe("API key (auto-detected from configured key if omitted)"),
           startDate: z.string().optional().describe("Start date (ISO format)"),
           endDate: z.string().optional().describe("End date (ISO format)"),
           chain: z.string().optional().describe("Filter by chain ID"),
@@ -644,8 +673,15 @@ const keplrRpcPlugin: KeplrPlugin = {
         },
         annotations: { readOnlyHint: true },
       },
-      async ({ apiKey, startDate, endDate, chain, endpointType }) => {
+      async ({
+        apiKey: explicitKey,
+        startDate,
+        endDate,
+        chain,
+        endpointType,
+      }) => {
         try {
+          const apiKey = resolveApiKey(explicitKey);
           const query: Record<string, string> = { clientType: "keplr-mcp" };
           if (startDate) query.startDate = startDate;
           if (endDate) query.endDate = endDate;
@@ -689,12 +725,16 @@ const keplrRpcPlugin: KeplrPlugin = {
           "Get Keplr Infra credit transaction history (top-ups, adjustments). " +
           "Use this after payment to verify the exact credit amount added instead of comparing usage summaries.",
         inputSchema: {
-          apiKey: z.string().describe("API key"),
+          apiKey: z
+            .string()
+            .optional()
+            .describe("API key (auto-detected from configured key if omitted)"),
         },
         annotations: { readOnlyHint: true },
       },
-      async ({ apiKey }) => {
+      async ({ apiKey: explicitKey }) => {
         try {
+          const apiKey = resolveApiKey(explicitKey);
           const raw = await keplrApiFetch<Record<string, unknown>>({
             method: "GET",
             path: `/v1/credits/${apiKey}/history`,

packages/server/src/rpc/resolver.ts

@@ -30,6 +30,11 @@ export class RpcResolver {
     return !!this.config.apiKey;
   }
 
+  /** The configured API key, if any. */
+  get apiKey(): string | undefined {
+    return this.config.apiKey;
+  }
+
   /**
    * Resolve the best RPC endpoint for a given chain ID.
    * Returns an object compatible with CosmJS HttpEndpoint interface.