@ekoindia/eps-context-mcp 0.1.3 → 0.1.4

package/README.md

@@ -15,9 +15,13 @@ fetch full detail when it needs it.
 No install step required — run it on demand with `npx`:
 
 ```bash
-npx -y @ekoindia/eps-context-mcp
+npx -y @ekoindia/eps-context-mcp@latest
 ```
 
+The `@latest` tag makes `npx` re-resolve the newest published version on each
+launch, so you always run the current server + API bundle without editing your
+config (see [Staying up to date](#staying-up-to-date)).
+
 The server speaks MCP over **stdio**, so it is meant to be launched by an MCP
 client (see per-harness config below) rather than run by hand. It logs its
 status to **stderr** and waits for an MCP client on stdin/stdout.
@@ -27,30 +31,37 @@ Requires **Node.js ≥ 18**.
 ## Tools
 
 All tools are read-only and **secret-free** — none of them accept an
-`access_key` or any other credential.
-
-| Tool | Arguments | Returns |
-| --- | --- | --- |
-| `list_apis` | `category?` | Compact index of EPS endpoints (no request/response bodies). Optional category filter. |
-| `list_topics` | — | Documentation topic ids: `auth`, `errors`, `pricing`, `environments`. |
-| `list_recipes` | — | Multi-step recipe ids + names (e.g. `dmt-send-money`, `aeps-cash-withdrawal`). |
-| `search` | `query` | Ranked endpoint matches for a query (ids only, no bodies). |
-| `get_api` | `slug` | Full detail for one endpoint (params, response fields, errors, examples). |
-| `get_topic` | `topic` (`auth` \| `errors` \| `pricing` \| `environments`) | One documentation topic. |
-| `get_recipe` | `id` | One multi-step recipe (steps + branches). |
-| `get_signing_snippet` | `language` (`php` \| `java` \| `csharp` \| `javascript` \| `python` \| `go`) | Paste-ready **backend** code to compute the request `secret-key`. |
-| `get_meta` | — | Bundle org/version + which data source is in use (`baked` or `remote`). |
+`access_key` or any other credential. Every tool also declares MCP annotations
+(`readOnlyHint: true`, `idempotentHint: true`, `openWorldHint: false`) so
+clients can see this programmatically.
+
+| Tool                  | Arguments                                                                    | Returns                                                                                                                                            |
+| --------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_apis`           | `category?`, `limit?`                                                        | Compact index of EPS endpoints (no request/response bodies). `category` is validated against the bundle's categories; all entries by default.      |
+| `list_topics`         | —                                                                            | Documentation topic ids: `auth`, `errors`, `pricing`, `environments`.                                                                              |
+| `list_recipes`        | —                                                                            | Multi-step recipe ids + names (e.g. `dmt-send-money`, `aeps-cash-withdrawal`).                                                                     |
+| `search`              | `query`, `limit?`                                                            | Ranked endpoint matches for a query (ids only, no bodies). Top 10 by default; raise `limit` for more.                                              |
+| `get_api`             | `slug`                                                                       | Full detail for one endpoint (params, response fields, errors, examples).                                                                          |
+| `get_topic`           | `topic` (`auth` \| `errors` \| `pricing` \| `environments`)                  | One documentation topic.                                                                                                                           |
+| `get_recipe`          | `id`                                                                         | One multi-step recipe (steps + branches).                                                                                                          |
+| `get_signing_snippet` | `language` (`php` \| `java` \| `csharp` \| `javascript` \| `python` \| `go`) | Paste-ready **backend** code to compute the request `secret-key`.                                                                                  |
+| `get_meta`            | —                                                                            | Bundle org/version, data source (`baked` or `remote`), this server's `packageVersion`, and `updateAvailable` (whether a newer npm release exists). |
 
 **Tiered usage:** start with `list_apis` / `search` (cheap, compact), then call
 `get_api` only for the endpoint(s) you actually need. Same pattern for
 `list_topics` → `get_topic` and `list_recipes` → `get_recipe`.
 
+**Errors are actionable:** an unknown `slug`/`id` returns an MCP error result
+(`isError: true`) with "did you mean" suggestions and a pointer to
+`search`/`list_apis`; an invalid `category` fails schema validation with the
+valid values listed.
+
 ## Client configuration
 
 ### Claude Code
 
 ```bash
-claude mcp add eps --scope project -- npx -y @ekoindia/eps-context-mcp
+claude mcp add eps --scope project -- npx -y @ekoindia/eps-context-mcp@latest
 ```
 
 `--scope project` writes a shared `.mcp.json` committed with the repo. Use
@@ -62,7 +73,10 @@ Or add to your MCP config (project `.mcp.json`, or `~/.claude.json` for user sco
 ```json
 {
 	"mcpServers": {
-		"eps": { "command": "npx", "args": ["-y", "@ekoindia/eps-context-mcp"] }
+		"eps": {
+			"command": "npx",
+			"args": ["-y", "@ekoindia/eps-context-mcp@latest"]
+		}
 	}
 }
 ```
@@ -74,7 +88,10 @@ Or add to your MCP config (project `.mcp.json`, or `~/.claude.json` for user sco
 ```json
 {
 	"mcpServers": {
-		"eps": { "command": "npx", "args": ["-y", "@ekoindia/eps-context-mcp"] }
+		"eps": {
+			"command": "npx",
+			"args": ["-y", "@ekoindia/eps-context-mcp@latest"]
+		}
 	}
 }
 ```
@@ -88,7 +105,7 @@ Or add to your MCP config (project `.mcp.json`, or `~/.claude.json` for user sco
 	"mcp": {
 		"eps": {
 			"type": "local",
-			"command": ["npx", "-y", "@ekoindia/eps-context-mcp"],
+			"command": ["npx", "-y", "@ekoindia/eps-context-mcp@latest"],
 			"enabled": true
 		}
 	}
@@ -103,7 +120,7 @@ Or add to your MCP config (project `.mcp.json`, or `~/.claude.json` for user sco
 mcpServers:
   - name: eps
     command: npx
-    args: ["-y", "@ekoindia/eps-context-mcp"]
+    args: ["-y", "@ekoindia/eps-context-mcp@latest"]
 ```
 
 ### Codex CLI
@@ -113,7 +130,7 @@ mcpServers:
 ```toml
 [mcp_servers.eps]
 command = "npx"
-args = ["-y", "@ekoindia/eps-context-mcp"]
+args = ["-y", "@ekoindia/eps-context-mcp@latest"]
 ```
 
 ### Gemini CLI
@@ -123,11 +140,30 @@ args = ["-y", "@ekoindia/eps-context-mcp"]
 ```json
 {
 	"mcpServers": {
-		"eps": { "command": "npx", "args": ["-y", "@ekoindia/eps-context-mcp"] }
+		"eps": {
+			"command": "npx",
+			"args": ["-y", "@ekoindia/eps-context-mcp@latest"]
+		}
 	}
 }
 ```
 
+## Staying up to date
+
+The package is auto-published on every merge to `main`, and each publish carries
+the freshest baked API bundle. To keep users current:
+
+- **Use `@latest` in your config** (all snippets above do). `npx` then
+  re-resolves the newest publish on each launch — no manual updates. Offline
+  launches fall back to the npx cache; pin `@<version>` if you need a frozen
+  build.
+- **Update check.** On startup the server does one best-effort request to the
+  npm registry (3s timeout). If a newer version is published, it logs a nudge to
+  **stderr** and sets `updateAvailable` on `get_meta` — so an agent can tell you
+  to switch to `@latest`. The check is silent on any failure (offline, proxy)
+  and never blocks startup. Set `EPS_NO_UPDATE_CHECK=1` to disable it entirely
+  (no network request).
+
 ## Configuration
 
 ### `EPS_BUNDLE_URL` (optional)
@@ -140,16 +176,16 @@ bundle at startup (e.g. the latest generated `eps.json`), set `EPS_BUNDLE_URL`:
 	"mcpServers": {
 		"eps": {
 			"command": "npx",
-			"args": ["-y", "@ekoindia/eps-context-mcp"],
+			"args": ["-y", "@ekoindia/eps-context-mcp@latest"],
 			"env": { "EPS_BUNDLE_URL": "https://eps.eko.in/agent/eps.json" }
 		}
 	}
 }
 ```
 
-If the fetch fails for any reason, the server transparently falls back to the
-baked bundle. `get_meta` reports which source is in effect (`baked` or
-`remote`).
+The remote fetch is capped at **5 seconds**; if it fails or times out for any
+reason, the server transparently falls back to the baked bundle. `get_meta`
+reports which source is in effect (`baked` or `remote`).
 
 ## Security: backend-only signing
 

package/data/eps.json

@@ -2,7 +2,7 @@
   "meta": {
     "org": "ekoindia",
     "apiVersion": "v3",
-    "bundleVersion": "5f1b3ac4",
+    "bundleVersion": "1e83ecd3",
     "environments": [
       {
         "id": "sandbox",
@@ -1856,8 +1856,8 @@
           "in": "header",
           "type": "string",
           "required": true,
-          "description": "application/json",
-          "example": "application/json"
+          "description": "multipart/form-data — let your HTTP client set this header itself (it generates the required boundary); do not hardcode the value.",
+          "example": "multipart/form-data"
         }
       ],
       "requestParams": [
@@ -1921,7 +1921,7 @@
         },
         {
           "name": "pan_card",
-          "type": "string",
+          "type": "file",
           "required": true,
           "description": "PAN card document upload (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB. PNG not accepted.",
           "example": "<binary file>",
@@ -1929,7 +1929,7 @@
         },
         {
           "name": "aadhar_front",
-          "type": "string",
+          "type": "file",
           "required": true,
           "description": "Front side of the Aadhaar card (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB.",
           "example": "<binary file>",
@@ -1937,7 +1937,7 @@
         },
         {
           "name": "aadhar_back",
-          "type": "string",
+          "type": "file",
           "required": true,
           "description": "Back side of the Aadhaar card (multipart/form-data). Accepted formats: JPEG, JPG, PDF. Max size: 1 MB.",
           "example": "<binary file>",

package/dist/index.js

@@ -1,6 +1,9 @@
 #!/usr/bin/env node
 
 // src/index.ts
+import { readFileSync } from "fs";
+import path2 from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/load-bundle.ts
@@ -13,7 +16,7 @@ var loadBundle = async () => {
   const url = process.env.EPS_BUNDLE_URL;
   if (url) {
     try {
-      const res = await fetch(url);
+      const res = await fetch(url, { signal: AbortSignal.timeout(5e3) });
       if (res.ok)
         return { bundle: await res.json(), source: "remote" };
     } catch {
@@ -39,19 +42,26 @@ var toIndexEntry = (a) => ({
   category: a.category,
   relevance: a.relevance
 });
-var listApis = (bundle, category) => bundle.apis.filter((a) => !category || a.category === category).map(toIndexEntry);
+var listApis = (bundle, category, limit) => {
+  const entries = bundle.apis.filter((a) => !category || a.category === category).map(toIndexEntry);
+  return limit !== void 0 ? entries.slice(0, limit) : entries;
+};
+var listCategories = (bundle) => [
+  ...new Set(bundle.apis.map((a) => a.category))
+];
 var listTopics = (bundle) => Object.keys(bundle.topics);
 var listRecipes = (bundle) => bundle.recipes.map((r) => ({ id: r.id, name: r.name, summary: r.summary }));
-var searchApis = (bundle, query) => {
+var searchApis = (bundle, query, limit) => {
   const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
-  if (!terms.length) return listApis(bundle);
+  if (!terms.length) return listApis(bundle, void 0, limit);
   const scored = bundle.apis.map((a) => {
     const hay = `${a.name} ${a.summary} ${a.path} ${a.category} ${a.productName}`.toLowerCase();
     let score = 0;
     for (const t of terms) if (hay.includes(t)) score += 1;
     return { a, score };
   });
-  return scored.filter((s) => s.score > 0).sort((x, y) => y.score - x.score).map((s) => toIndexEntry(s.a));
+  const ranked = scored.filter((s) => s.score > 0).sort((x, y) => y.score - x.score).map((s) => toIndexEntry(s.a));
+  return limit !== void 0 ? ranked.slice(0, limit) : ranked;
 };
 var getApi = (bundle, slug) => bundle.apis.find((a) => a.slug === slug);
 var getTopic = (bundle, topic) => bundle.topics[topic];
@@ -146,28 +156,46 @@ var getSigningSnippet = (language) => SNIPPETS[language] ?? `Unsupported languag
 
 // src/server.ts
 var json = (value) => ({
-  content: [{ type: "text", text: JSON.stringify(value, null, 2) }]
+  content: [{ type: "text", text: JSON.stringify(value) }]
 });
-var createEpsServer = (bundle, source) => {
+var notFound = (message) => ({
+  isError: true,
+  content: [{ type: "text", text: message }]
+});
+var READ_ONLY = {
+  readOnlyHint: true,
+  idempotentHint: true,
+  openWorldHint: false
+};
+var DEFAULT_SEARCH_LIMIT = 10;
+var createEpsServer = (bundle, source, versionState) => {
   const server = new McpServer({
     name: "eps-context-mcp",
     version: bundle.meta.bundleVersion
   });
+  const categories = listCategories(bundle);
+  const categorySchema = categories.length ? z.enum(categories) : z.string();
+  const limitSchema = z.number().int().positive().optional();
   server.registerTool(
     "list_apis",
     {
       title: "List EPS APIs",
-      description: "Compact index of EPS API endpoints (no request/response bodies). Optionally filter by category.",
-      inputSchema: { category: z.string().optional() }
+      description: "Compact index of EPS API endpoints (no request/response bodies). Unfiltered, all ~99 entries are returned (the full tiered index); narrow with category and/or limit when you don't need everything.",
+      inputSchema: {
+        category: categorySchema.optional().describe(`One of: ${categories.join(", ")}`),
+        limit: limitSchema.describe("Max entries to return (default: all)")
+      },
+      annotations: READ_ONLY
     },
-    async ({ category }) => json(listApis(bundle, category))
+    async ({ category, limit }) => json(listApis(bundle, category, limit))
   );
   server.registerTool(
     "list_topics",
     {
       title: "List topics",
       description: "List documentation topic ids.",
-      inputSchema: {}
+      inputSchema: {},
+      annotations: READ_ONLY
     },
     async () => json(listTopics(bundle))
   );
@@ -176,7 +204,8 @@ var createEpsServer = (bundle, source) => {
     {
       title: "List recipes",
       description: "List multi-step recipe ids + names.",
-      inputSchema: {}
+      inputSchema: {},
+      annotations: READ_ONLY
     },
     async () => json(listRecipes(bundle))
   );
@@ -184,21 +213,34 @@ var createEpsServer = (bundle, source) => {
     "search",
     {
       title: "Search APIs",
-      description: "Ranked endpoint matches for a query (ids only, no bodies).",
-      inputSchema: { query: z.string() }
+      description: `Ranked endpoint matches for a query (ids only, no bodies). Returns the top ${DEFAULT_SEARCH_LIMIT} by default; raise limit for more.`,
+      inputSchema: {
+        query: z.string(),
+        limit: limitSchema.describe(
+          `Max results (default ${DEFAULT_SEARCH_LIMIT})`
+        )
+      },
+      annotations: READ_ONLY
     },
-    async ({ query }) => json(searchApis(bundle, query))
+    async ({ query, limit }) => json(searchApis(bundle, query, limit ?? DEFAULT_SEARCH_LIMIT))
   );
   server.registerTool(
     "get_api",
     {
       title: "Get API detail",
       description: "Full detail for one endpoint by slug.",
-      inputSchema: { slug: z.string() }
+      inputSchema: { slug: z.string() },
+      annotations: READ_ONLY
     },
     async ({ slug }) => {
       const api = getApi(bundle, slug);
-      return api ? json(api) : json({ error: `Unknown slug "${slug}"` });
+      if (api) return json(api);
+      const suggestions = searchApis(bundle, slug.replace(/[-_]/g, " "), 3).map(
+        (a) => a.slug
+      );
+      return notFound(
+        `Unknown slug "${slug}".` + (suggestions.length ? ` Did you mean: ${suggestions.join(", ")}?` : "") + ` Use search or list_apis to find valid slugs.`
+      );
     }
   );
   server.registerTool(
@@ -208,7 +250,8 @@ var createEpsServer = (bundle, source) => {
       description: "One topic: auth | errors | pricing | environments.",
       inputSchema: {
         topic: z.enum(["auth", "errors", "pricing", "environments"])
-      }
+      },
+      annotations: READ_ONLY
     },
     async ({ topic }) => json(getTopic(bundle, topic))
   );
@@ -217,11 +260,16 @@ var createEpsServer = (bundle, source) => {
     {
       title: "Get recipe",
       description: "One multi-step recipe (steps + branches) by id.",
-      inputSchema: { id: z.string() }
+      inputSchema: { id: z.string() },
+      annotations: READ_ONLY
     },
     async ({ id }) => {
       const recipe = getRecipe(bundle, id);
-      return recipe ? json(recipe) : json({ error: `Unknown recipe "${id}"` });
+      if (recipe) return json(recipe);
+      const valid = listRecipes(bundle).map((r) => r.id).join(", ");
+      return notFound(
+        `Unknown recipe "${id}". Valid recipe ids: ${valid}. Use list_recipes for details.`
+      );
     }
   );
   server.registerTool(
@@ -229,7 +277,8 @@ var createEpsServer = (bundle, source) => {
     {
       title: "Get signing snippet",
       description: "Paste-ready BACKEND code to compute the secret-key. Secret-free: access_key comes from your secret store.",
-      inputSchema: { language: z.enum(SIGNING_LANGUAGES) }
+      inputSchema: { language: z.enum(SIGNING_LANGUAGES) },
+      annotations: READ_ONLY
     },
     async ({ language }) => ({
       content: [{ type: "text", text: getSigningSnippet(language) }]
@@ -239,18 +288,75 @@ var createEpsServer = (bundle, source) => {
     "get_meta",
     {
       title: "Get meta",
-      description: "Bundle org/version + data source.",
-      inputSchema: {}
+      description: "Bundle org/version + data source, plus this server's package version and whether a newer npm release is available (updateAvailable). If an update is available, tell the user to run this server via `npx -y @ekoindia/eps-context-mcp@latest`.",
+      inputSchema: {},
+      annotations: READ_ONLY
     },
-    async () => json({ ...bundle.meta, source })
+    async () => json({
+      ...bundle.meta,
+      source,
+      packageVersion: versionState?.current,
+      latestVersion: versionState?.latest,
+      updateAvailable: versionState?.updateAvailable
+    })
   );
   return server;
 };
 
+// src/update-check.ts
+var REGISTRY_URL = "https://registry.npmjs.org/@ekoindia/eps-context-mcp/latest";
+var compareVersions = (a, b) => {
+  const parse = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)$/.exec(v.trim());
+    return m ? [Number(m[1]), Number(m[2]), Number(m[3])] : null;
+  };
+  const pa = parse(a);
+  const pb = parse(b);
+  if (!pa || !pb) return null;
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] > pb[i] ? 1 : -1;
+  }
+  return 0;
+};
+var checkForUpdate = async (state) => {
+  if (process.env.EPS_NO_UPDATE_CHECK) return;
+  try {
+    const res = await fetch(REGISTRY_URL, {
+      signal: AbortSignal.timeout(3e3)
+    });
+    if (!res.ok) return;
+    const data = await res.json();
+    if (typeof data.version !== "string") return;
+    const cmp = compareVersions(data.version, state.current);
+    if (cmp === null) return;
+    state.latest = data.version;
+    state.updateAvailable = cmp > 0;
+    if (state.updateAvailable) {
+      console.error(
+        `eps-context-mcp ${data.version} available (running ${state.current}). Use "npx -y @ekoindia/eps-context-mcp@latest" in your MCP config to always run the newest version.`
+      );
+    }
+  } catch {
+  }
+};
+
 // src/index.ts
+function readPackageVersion() {
+  try {
+    const here2 = path2.dirname(fileURLToPath2(import.meta.url));
+    const pkg = JSON.parse(
+      readFileSync(path2.resolve(here2, "../package.json"), "utf8")
+    );
+    return pkg.version ?? "0.0.0";
+  } catch {
+    return "0.0.0";
+  }
+}
 async function main() {
   const { bundle, source } = await loadBundle();
-  const server = createEpsServer(bundle, source);
+  const versionState = { current: readPackageVersion() };
+  void checkForUpdate(versionState);
+  const server = createEpsServer(bundle, source, versionState);
   const transport = new StdioServerTransport();
   await server.connect(transport);
   console.error(

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@ekoindia/eps-context-mcp",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"description": "Local MCP server giving AI coding agents context for Eko Platform Services (EPS) APIs.",
 	"license": "MIT",
 	"type": "module",
@@ -23,11 +23,12 @@
 		"bake": "node scripts/bake-bundle.mjs",
 		"build": "tsup",
 		"test": "vitest run",
+		"typecheck": "tsc --noEmit",
 		"prepublishOnly": "npm run bake && npm run build"
 	},
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.0.0",
-		"zod": "^3.25.76"
+		"zod": "^4.0.0"
 	},
 	"devDependencies": {
 		"tsup": "^8.0.0",