doora-mcp 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# doora-mcp
+
+Model Context Protocol server for [doora](https://www.doora.to) — let
+Claude Desktop / Cursor / Continue / Zed (or anything else that
+speaks MCP) look up addresses by doora handle.
+
+## Install
+
+The server runs via `npx`. No local install needed. Drop this block
+into your MCP client's config and restart:
+
+```jsonc
+// Claude Desktop on macOS:
+// ~/Library/Application Support/Claude/claude_desktop_config.json
+{
+  "mcpServers": {
+    "doora": {
+      "command": "npx",
+      "args": ["-y", "doora-mcp"],
+      "env": {
+        "DOORA_API_KEY": "dk_test_..."
+      }
+    }
+  }
+}
+```
+
+You should see "doora" in Claude Desktop's available-tools panel.
+
+For Cursor, Continue, Zed, and other clients, see
+**https://www.doora.to/docs/mcp** for per-client config snippets.
+
+## Get an API key
+
+You'll need a doora merchant API key in the `DOORA_API_KEY` env
+slot. Two flavours:
+
+- **`dk_test_…`** — sandbox key. Resolves only the curated `demo@*`
+  handles. Safe to put in a config file shared with collaborators.
+- **`dk_live_…`** — production key, resolves real handles your
+  merchant integration is authorised for.
+
+Request a key via [the contact form](https://www.doora.to/contact).
+
+The MCP server makes no auth check at startup — Claude can start it
+and list its tools, and only sees a friendly "configure DOORA_API_KEY"
+error when you first try to resolve a handle.
+
+## Tools
+
+| Tool | What it does | Network |
+|---|---|---|
+| `resolve_handle` | Look up address for a `username@label` handle | ✓ |
+| `encode_digipin` | lat/lng → 12-char DIGIPIN string | — |
+| `decode_digipin` | DIGIPIN → lat/lng centroid | — |
+| `list_demo_handles` | Curated list of test-key-resolvable handles | — |
+| `validate_handle_shape` | Regex-check a handle without an API call | — |
+
+Full reference with example prompts and trust model at
+**https://www.doora.to/docs/mcp**.
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `DOORA_API_KEY` | *(required)* | Bearer token for resolve calls |
+| `DOORA_BASE_URL` | `https://www.doora.to` | Override for self-hosted deployments |
+
+## Support
+
+- **Docs:** https://www.doora.to/docs/mcp
+- **Contact:** https://www.doora.to/contact
+
+## License
+
+MIT.

package/dist/api-client.js

@@ -0,0 +1,68 @@
+/**
+ * HTTP client wrapping the doora merchant API.
+ *
+ * Reads:
+ *   DOORA_API_KEY  required for every tool that hits the server.
+ *                  Format: `dk_test_…` or `dk_live_…`.
+ *   DOORA_BASE_URL optional, defaults to https://www.doora.to.
+ *                  Override only for staging / local dev.
+ *
+ * Important: we DO NOT validate DOORA_API_KEY at module load. That
+ * would block the MCP server from booting (and listing its tools to
+ * Claude Desktop) just because the user hadn't configured the key
+ * yet. Instead we surface the missing-key error at tool-invocation
+ * time with a clear message pointing at the fix.
+ */
+const DEFAULT_BASE_URL = 'https://www.doora.to';
+export class DoraApiError extends Error {
+    status;
+    body;
+    constructor(status, body, message) {
+        super(message);
+        this.name = 'DoraApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+/** Throws a tagged error when DOORA_API_KEY is missing. Caller turns
+ *  this into a friendly tool response. */
+function readApiKey() {
+    const key = process.env.DOORA_API_KEY?.trim();
+    if (!key) {
+        throw new DoraApiError(0, null, 'DOORA_API_KEY environment variable not set. Configure it in your MCP client config (e.g. in claude_desktop_config.json under env). See https://www.doora.to/docs/mcp for setup.');
+    }
+    return key;
+}
+function baseUrl() {
+    const raw = process.env.DOORA_BASE_URL?.trim() || DEFAULT_BASE_URL;
+    return raw.replace(/\/+$/, '');
+}
+async function request(path, init = {}) {
+    const key = readApiKey();
+    const headers = new Headers(init.headers);
+    headers.set('authorization', `Bearer ${key}`);
+    if (init.body && !headers.has('content-type')) {
+        headers.set('content-type', 'application/json');
+    }
+    // Tag every call so doora can identify MCP traffic in its logs
+    // (useful for usage analytics + isolating issues to this client).
+    headers.set('user-agent', `doora-mcp/${process.env.npm_package_version ?? 'dev'} (+https://www.doora.to/docs/mcp)`);
+    const url = `${baseUrl()}${path}`;
+    const res = await fetch(url, { ...init, headers });
+    let body = null;
+    try {
+        body = await res.json();
+    }
+    catch { /* response wasn't JSON, leave body=null */ }
+    if (!res.ok) {
+        const msg = (typeof body === 'object' && body && 'error' in body && typeof body.error === 'string')
+            ? body.error
+            : `HTTP ${res.status} at ${path}`;
+        throw new DoraApiError(res.status, body, msg);
+    }
+    return body;
+}
+export async function resolveHandle(handle) {
+    const trimmed = handle.trim().toLowerCase();
+    return request(`/api/v1/resolve?handle=${encodeURIComponent(trimmed)}`);
+}

package/dist/digipin.js

@@ -0,0 +1,107 @@
+/**
+ * DIGIPIN encoder / decoder — TypeScript port of India Post's
+ * reference implementation, inlined here so the MCP package has no
+ * runtime dependency on the main doora monorepo.
+ *
+ * Mirrors lib/digipin.ts in the main repo exactly. Both files MUST
+ * stay in sync; the unit suite at tests/unit/digipin.test.ts pins
+ * the shape that both sides must produce. If you change the grid,
+ * the bounding box, or the levels here, update the main lib AND
+ * re-run the tests there.
+ *
+ * 10-character output (12 with separators). Each character bisects
+ * the bounding box four ways, so level 10 lands inside a ~4m × 4m
+ * cell. We only target India — the bounding box is hard-coded.
+ */
+const GRID = [
+    ['F', 'C', '9', '8'],
+    ['J', '3', '2', '7'],
+    ['K', '4', '5', '6'],
+    ['L', 'M', 'P', 'T'],
+];
+export const DIGIPIN_BOUNDS = {
+    minLat: 2.5,
+    maxLat: 38.5,
+    minLon: 63.5,
+    maxLon: 99.5,
+};
+const LEVELS = 10;
+const CHAR_INDEX = (() => {
+    const map = new Map();
+    for (let r = 0; r < 4; r++) {
+        for (let c = 0; c < 4; c++) {
+            map.set(GRID[r][c], [r, c]);
+        }
+    }
+    return map;
+})();
+/** Returns the 12-character DIGIPIN string ("XXX-XXX-XXXX") for a
+ *  point inside the India bounding box, or null for inputs outside
+ *  it (NaN, Antarctica, the moon). */
+export function encodeDigipin(lat, lon) {
+    if (!Number.isFinite(lat) || !Number.isFinite(lon))
+        return null;
+    if (lat < DIGIPIN_BOUNDS.minLat || lat > DIGIPIN_BOUNDS.maxLat)
+        return null;
+    if (lon < DIGIPIN_BOUNDS.minLon || lon > DIGIPIN_BOUNDS.maxLon)
+        return null;
+    let minLat = DIGIPIN_BOUNDS.minLat;
+    let maxLat = DIGIPIN_BOUNDS.maxLat;
+    let minLon = DIGIPIN_BOUNDS.minLon;
+    let maxLon = DIGIPIN_BOUNDS.maxLon;
+    let pin = '';
+    for (let level = 1; level <= LEVELS; level++) {
+        const latDiv = (maxLat - minLat) / 4;
+        const lonDiv = (maxLon - minLon) / 4;
+        let row = 3 - Math.floor((lat - minLat) / latDiv);
+        let col = Math.floor((lon - minLon) / lonDiv);
+        if (row < 0)
+            row = 0;
+        else if (row > 3)
+            row = 3;
+        if (col < 0)
+            col = 0;
+        else if (col > 3)
+            col = 3;
+        pin += GRID[row][col];
+        if (level === 3 || level === 6)
+            pin += '-';
+        const newMaxLat = minLat + latDiv * (4 - row);
+        const newMinLat = minLat + latDiv * (3 - row);
+        maxLat = newMaxLat;
+        minLat = newMinLat;
+        const newMinLon = minLon + lonDiv * col;
+        minLon = newMinLon;
+        maxLon = newMinLon + lonDiv;
+    }
+    return pin;
+}
+/** Decodes a 10-char DIGIPIN string (dashes optional, case-
+ *  insensitive) back to the centroid lat/lng of its level-10 cell.
+ *  Throws RangeError on malformed input — callers catch + repackage. */
+export function decodeDigipin(digipin) {
+    const pin = digipin.toUpperCase().replace(/-/g, '');
+    if (pin.length !== 10) {
+        throw new RangeError(`DIGIPIN must be 10 chars (got ${pin.length})`);
+    }
+    let minLat = DIGIPIN_BOUNDS.minLat;
+    let maxLat = DIGIPIN_BOUNDS.maxLat;
+    let minLon = DIGIPIN_BOUNDS.minLon;
+    let maxLon = DIGIPIN_BOUNDS.maxLon;
+    for (let i = 0; i < LEVELS; i++) {
+        const idx = CHAR_INDEX.get(pin[i]);
+        if (!idx)
+            throw new RangeError(`Invalid DIGIPIN character "${pin[i]}"`);
+        const [ri, ci] = idx;
+        const latDiv = (maxLat - minLat) / 4;
+        const lonDiv = (maxLon - minLon) / 4;
+        minLat = maxLat - latDiv * (ri + 1);
+        maxLat = maxLat - latDiv * ri;
+        minLon = minLon + lonDiv * ci;
+        maxLon = minLon + lonDiv;
+    }
+    return {
+        lat: (minLat + maxLat) / 2,
+        lng: (minLon + maxLon) / 2,
+    };
+}

package/dist/index.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/**
+ * doora-mcp — Model Context Protocol server for doora.
+ *
+ * Lets an LLM agent (Claude Desktop, Cursor, Continue, etc.) look up
+ * addresses by doora handle, decode + encode DIGIPINs, and discover
+ * the demo handles available to test against.
+ *
+ * Install + run:
+ *
+ *   $ npx -y doora-mcp        (Claude Desktop launches us this way)
+ *
+ * Configure in Claude Desktop (~/Library/Application Support/Claude/
+ * claude_desktop_config.json on macOS):
+ *
+ *   {
+ *     "mcpServers": {
+ *       "doora": {
+ *         "command": "npx",
+ *         "args": ["-y", "doora-mcp"],
+ *         "env": { "DOORA_API_KEY": "dk_test_..." }
+ *       }
+ *     }
+ *   }
+ *
+ * Architecture notes:
+ *
+ *   - stdio transport only (v1). Claude Desktop + Cursor + Continue
+ *     all support stdio out of the box. SSE/HTTP transport adds
+ *     hosting overhead we don't need yet.
+ *
+ *   - Tools are stateless. Each call is independent — no session,
+ *     no cookies, just an API key in the bearer header. That keeps
+ *     the surface boring + auditable.
+ *
+ *   - We DO NOT probe DOORA_API_KEY at startup. Claude Desktop
+ *     happily starts servers whose env isn't configured yet; the
+ *     friendly "missing key" message lands at first tool call.
+ *
+ *   - Every tool returns text content (not embedded JSON) so the
+ *     LLM has the easiest time reading what came back. Pretty-
+ *     printed JSON in a code block is the lingua franca.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { encodeDigipin, decodeDigipin } from './digipin.js';
+import { DoraApiError, resolveHandle } from './api-client.js';
+const HANDLE_PATTERN = /^([a-z0-9-]{3,24})@([a-z0-9-]{2,16})$/i;
+const server = new McpServer({
+    name: 'doora',
+    version: '0.1.0',
+}, {
+    capabilities: { tools: {} },
+    instructions: `doora exposes India-aware addresses behind memorable handles like \`praneeth@home\`. ` +
+        `Use these tools whenever the user asks to look up an address by handle, ` +
+        `encode coordinates to a DIGIPIN, decode a DIGIPIN to coordinates, ` +
+        `or check whether a string is a valid doora handle. ` +
+        `Call list_demo_handles first if you need a sandbox handle to demonstrate against.`,
+});
+// ─── Tool 1: resolve_handle ──────────────────────────────────────────
+server.registerTool('resolve_handle', {
+    title: 'Resolve doora handle to address',
+    description: 'Look up the full delivery address for a doora handle. Returns coordinates, ' +
+        'DIGIPIN, building/floor/unit fields the owner has shared, verification method, ' +
+        'and an audit id. Use this when the user mentions any string in `username@label` ' +
+        'shape (e.g. "praneeth@home", "demo@office") and wants the underlying address. ' +
+        'Requires the DOORA_API_KEY environment variable; test keys can only resolve ' +
+        'handles owned by the configured demo user — call list_demo_handles to see those.',
+    inputSchema: {
+        handle: z.string()
+            .describe('Doora handle in the form `username@label`. Case-insensitive; will be lowercased before lookup.'),
+    },
+}, async ({ handle }) => {
+    try {
+        const result = await resolveHandle(handle);
+        return {
+            content: [
+                { type: 'text', text: formatResolveResult(result) },
+            ],
+        };
+    }
+    catch (e) {
+        return errorContent(e, `Could not resolve "${handle}"`);
+    }
+});
+// ─── Tool 2: encode_digipin ──────────────────────────────────────────
+server.registerTool('encode_digipin', {
+    title: 'Encode lat/lng to DIGIPIN',
+    description: 'Convert a latitude+longitude pair (in India) to a DIGIPIN — India Post\'s open ' +
+        'national geocode. Output is a 10-character (12 with separators) string identifying ' +
+        'a ~4m × 4m cell. Pure local computation; no network call, no API key needed. ' +
+        'Returns null for coordinates outside India.',
+    inputSchema: {
+        lat: z.number().min(2.5).max(38.5).describe('Latitude in degrees, within India\'s bounding box.'),
+        lng: z.number().min(63.5).max(99.5).describe('Longitude in degrees, within India\'s bounding box.'),
+    },
+}, async ({ lat, lng }) => {
+    const pin = encodeDigipin(lat, lng);
+    if (!pin) {
+        return {
+            content: [{ type: 'text', text: `Coordinates (${lat}, ${lng}) are outside the India bounding box; no DIGIPIN exists.` }],
+            isError: true,
+        };
+    }
+    return {
+        content: [
+            { type: 'text', text: `DIGIPIN for (${lat.toFixed(6)}, ${lng.toFixed(6)}):\n\n\`${pin}\`\n\nResolution: ~4m × 4m cell.` },
+        ],
+    };
+});
+// ─── Tool 3: decode_digipin ──────────────────────────────────────────
+server.registerTool('decode_digipin', {
+    title: 'Decode DIGIPIN to lat/lng',
+    description: 'Convert a DIGIPIN (10-char India Post geocode) back to latitude+longitude. ' +
+        'Dashes and case are tolerated (`422-36L-P8FM`, `42236lp8fm` both work). The ' +
+        'returned point is the centroid of the level-10 cell — accurate to within ~2m of ' +
+        'the original encoded point. Pure local computation; no network call.',
+    inputSchema: {
+        digipin: z.string().min(10).describe('A 10-character DIGIPIN string. Dashes and case are ignored.'),
+    },
+}, async ({ digipin }) => {
+    try {
+        const { lat, lng } = decodeDigipin(digipin);
+        return {
+            content: [
+                { type: 'text', text: `\`${digipin}\` decodes to:\n\n  lat: ${lat}\n  lng: ${lng}\n\nOpen in Google Maps: https://maps.google.com/?q=${lat},${lng}` },
+            ],
+        };
+    }
+    catch (e) {
+        const msg = e instanceof Error ? e.message : String(e);
+        return {
+            content: [{ type: 'text', text: `Failed to decode "${digipin}": ${msg}` }],
+            isError: true,
+        };
+    }
+});
+// ─── Tool 4: list_demo_handles ───────────────────────────────────────
+server.registerTool('list_demo_handles', {
+    title: 'List demo handles available to test keys',
+    description: 'Return the curated set of handles a `dk_test_` API key can resolve. Use this ' +
+        'when you need a known-good handle to demonstrate the resolve_handle tool, OR ' +
+        'when a resolve attempt returned 404 against a test key and you want to suggest ' +
+        'an alternative the user can try. Static list — no network call.',
+    inputSchema: {},
+}, async () => {
+    const handles = [
+        { handle: 'demo@home', note: 'Happy path: apartment in Hyderabad. All address fields visible, walk_and_lock verified to ~4m.' },
+        { handle: 'demo@office', note: 'Office building. building + floor visible; unit hidden (returns null).' },
+        { handle: 'demo@gate', note: 'Manual-satellite verification, larger accuracy. Tests the "low-precision pin" branch.' },
+        { handle: 'demo@private', note: 'Owner set privacy_mode=private. Returns 404 — verify your handler treats this the same as "doesn\'t exist".' },
+    ];
+    return {
+        content: [
+            {
+                type: 'text',
+                text: 'Demo handles available to test keys:\n\n' + handles.map((h) => `• \`${h.handle}\` — ${h.note}`).join('\n') +
+                    '\n\nAny other handle (or a live-only handle resolved with a test key) returns 404 by design — see https://www.doora.to/docs/api#demo-handles for the full rationale.',
+            },
+        ],
+    };
+});
+// ─── Tool 5: validate_handle_shape ───────────────────────────────────
+server.registerTool('validate_handle_shape', {
+    title: 'Validate doora handle shape',
+    description: 'Check whether a string is a structurally valid doora handle (`username@label`) ' +
+        'without hitting the API. Useful before calling resolve_handle to surface a clear ' +
+        'error message to the user. Pure regex; no network call, no API key.',
+    inputSchema: {
+        input: z.string().describe('The string to validate. Will be trimmed + lowercased before checking.'),
+    },
+}, async ({ input }) => {
+    const normalized = input.trim().toLowerCase();
+    const m = normalized.match(HANDLE_PATTERN);
+    if (!m) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `"${input}" is NOT a valid doora handle.\n\nA handle has the form \`username@label\`:\n  • username: 3-24 chars, lowercase a-z, 0-9, hyphen\n  • label:    2-16 chars, lowercase a-z, 0-9, hyphen\n  • exactly one \`@\` between them\n\nExamples that ARE valid: praneeth@home, demo@office, 0x-viking@flat-2.`,
+                },
+            ],
+        };
+    }
+    const [, username, label] = m;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `"${input}" IS a valid doora handle.\n\n  normalized: ${normalized}\n  username:   ${username}\n  label:      ${label}\n\nCall resolve_handle with the normalized form to look up the address.`,
+            },
+        ],
+    };
+});
+// ─── Helpers ────────────────────────────────────────────────────────
+function formatResolveResult(r) {
+    // The address payload is most readable when pretty-printed as JSON
+    // inside a code block. Mode + audit id surface above the block so
+    // the LLM can mention them without re-parsing JSON.
+    return [
+        `**${r.handle}** resolved (mode: ${r.mode}, audit: ${r.audit_id.slice(0, 8)}…)`,
+        '',
+        '```json',
+        JSON.stringify(r, null, 2),
+        '```',
+    ].join('\n');
+}
+function errorContent(e, prefix) {
+    if (e instanceof DoraApiError) {
+        const status = e.status === 0 ? 'setup' : `${e.status}`;
+        return {
+            content: [{ type: 'text', text: `${prefix}: ${e.message} (${status})` }],
+            isError: true,
+        };
+    }
+    const msg = e instanceof Error ? e.message : String(e);
+    return {
+        content: [{ type: 'text', text: `${prefix}: ${msg}` }],
+        isError: true,
+    };
+}
+// ─── Start ──────────────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Note: do NOT console.log here — stdout is the MCP transport
+    // channel. Any stray output corrupts the JSON-RPC stream. Use
+    // console.error for diagnostics (stderr is safe to log to).
+    console.error(`[doora-mcp] connected via stdio. base url: ${process.env.DOORA_BASE_URL || 'https://www.doora.to'}`);
+}
+main().catch((err) => {
+    console.error('[doora-mcp] fatal:', err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "doora-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for doora — let Claude / Cursor / Continue look up addresses by doora handle.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "doora",
+    "address",
+    "digipin",
+    "india",
+    "claude"
+  ],
+  "homepage": "https://www.doora.to/docs/mcp",
+  "bugs": "https://www.doora.to/contact",
+  "license": "MIT",
+  "author": "doora",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "bin": {
+    "doora-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "npm run build",
+    "smoke": "node scripts/smoke.mjs",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4"
+  },
+  "devDependencies": {
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.10.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}