doc-sample-mcp 0.1.0

package/README.md

@@ -0,0 +1,87 @@
+# DocSample MCP
+
+MCP server for the DocSample public API. It exposes read-only tools for AI
+clients to list and read documents through the dedicated `/api/mcp` endpoints.
+
+Repository: <https://github.com/juan-malonso/doc-sample-mcp>
+
+## Tools
+
+- `list_documents`: list document summaries by `country` and `type`.
+- `get_document`: get one document and its base64 files by `country`, `type`, and `id`.
+
+## Requirements
+
+- Node.js 20 or newer.
+- A DocSample API key with the permissions required by the tools you want to use:
+  `mcp:list` and/or `mcp:read`.
+
+## Install
+
+```bash
+git clone https://github.com/juan-malonso/doc-sample-mcp.git
+cd doc-sample-mcp
+npm install
+npm run build
+```
+
+## MCP Client Configuration
+
+Register the built server in your MCP client:
+
+```json
+{
+  "mcpServers": {
+    "doc-sample-api": {
+      "command": "node",
+      "args": ["/absolute/path/to/doc-sample-mcp/dist/index.js"],
+      "env": {
+        "DOC_SAMPLE_BASE_URL": "https://doc-sample.pages.dev",
+        "DOC_SAMPLE_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "doc-sample-api-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/doc-sample-mcp/dist/index.js"],
+      "env": {
+        "DOC_SAMPLE_BASE_URL": "http://localhost:3000",
+        "DOC_SAMPLE_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+## Publish To npm
+
+The package is ready to publish if you want one-command installs:
+
+```bash
+npm publish --access public
+```
+
+After publishing, MCP clients can use `npx`:
+
+```json
+{
+  "mcpServers": {
+    "doc-sample-api": {
+      "command": "npx",
+      "args": ["-y", "doc-sample-mcp"],
+      "env": {
+        "DOC_SAMPLE_BASE_URL": "https://doc-sample.pages.dev",
+        "DOC_SAMPLE_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+const DOCUMENT_TYPES = [
+    "PASSPORT",
+    "ID_CARD",
+    "DRIVER_LICENSE",
+    "RESIDENT",
+];
+const env = readEnvironment();
+const server = new McpServer({
+    name: "doc-sample-api",
+    version: "0.1.0",
+});
+server.registerTool("list_documents", {
+    title: "List documents",
+    description: "List document summaries by ISO alpha-2 country code and document type.",
+    inputSchema: {
+        country: z
+            .string()
+            .min(2)
+            .max(2)
+            .describe("ISO 3166-1 alpha-2 country code, for example ES or DE."),
+        type: z.enum(DOCUMENT_TYPES).describe("Document type."),
+    },
+}, async ({ country, type }) => {
+    const payload = await requestJson(`/api/mcp/${encodeURIComponent(country.toUpperCase())}/${type}`);
+    return asJsonContent(payload);
+});
+server.registerTool("get_document", {
+    title: "Get document",
+    description: "Get one document and its files as base64 by country, type, and numeric id.",
+    inputSchema: {
+        country: z
+            .string()
+            .min(2)
+            .max(2)
+            .describe("ISO 3166-1 alpha-2 country code, for example ES or DE."),
+        type: z.enum(DOCUMENT_TYPES).describe("Document type."),
+        id: z.number().int().positive().describe("Document id."),
+    },
+}, async ({ country, type, id }) => {
+    const payload = await requestJson(`/api/mcp/${encodeURIComponent(country.toUpperCase())}/${type}/${id}`);
+    return asJsonContent(payload);
+});
+server.registerResource("api-configuration", "doc-sample://configuration", {
+    title: "DocSample API configuration",
+    description: "Current DocSample API base URL used by this MCP server.",
+    mimeType: "application/json",
+}, async (uri) => ({
+    contents: [
+        {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify({
+                baseUrl: env.baseUrl,
+                availableDocumentTypes: DOCUMENT_TYPES,
+                requiredPermissions: ["mcp:list", "mcp:read"],
+            }, null, 2),
+        },
+    ],
+}));
+const transport = new StdioServerTransport();
+await server.connect(transport);
+function readEnvironment() {
+    const baseUrl = process.env.DOC_SAMPLE_BASE_URL?.replace(/\/+$/, "");
+    const apiKey = process.env.DOC_SAMPLE_API_KEY;
+    if (!baseUrl) {
+        throw new Error("DOC_SAMPLE_BASE_URL is required");
+    }
+    if (!apiKey) {
+        throw new Error("DOC_SAMPLE_API_KEY is required");
+    }
+    return { baseUrl, apiKey };
+}
+async function requestJson(path, method = "GET") {
+    const response = await fetch(`${env.baseUrl}${path}`, {
+        method,
+        headers: {
+            "x-api-key": env.apiKey,
+        },
+    });
+    const text = await response.text();
+    const payload = parseJson(text);
+    if (!response.ok) {
+        throw new Error(`DocSample API returned ${response.status}: ${formatErrorPayload(payload, text)}`);
+    }
+    return payload;
+}
+function parseJson(text) {
+    if (text.length === 0)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+function formatErrorPayload(payload, rawText) {
+    if (typeof payload === "object" &&
+        payload !== null &&
+        "message" in payload &&
+        typeof payload.message === "string") {
+        return payload.message;
+    }
+    if (typeof payload === "object" &&
+        payload !== null &&
+        "error" in payload &&
+        typeof payload.error === "string") {
+        return payload.error;
+    }
+    return rawText || "Request failed";
+}
+function asJsonContent(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "doc-sample-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for the DocSample public API.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "doc-sample-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run type-check && npm run build",
+    "type-check": "tsc -p tsconfig.json --noEmit",
+    "start": "node dist/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/juan-malonso/doc-sample-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "doc-sample"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.5",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.7",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}