doora-mcp 0.1.0 → 0.3.0

package/README.md

@@ -48,15 +48,20 @@ 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
+| Tool | What it does | Network | Needs `DOORA_API_KEY` |
+|---|---|---|---|
+| `resolve_handle` | Look up address for a `username@label` handle | ✓ | yes |
+| `start_handle_creation` | Mint a device-flow session so the user can create a new handle in their browser. Returns a `claim_url` to show them. | ✓ | **no** |
+| `check_handle_status` | Poll the result of `start_handle_creation` until the user finishes. | ✓ | **no** |
+| `encode_digipin` | lat/lng → 12-char DIGIPIN string | — | no |
+| `decode_digipin` | DIGIPIN → lat/lng centroid | — | no |
+| `list_demo_handles` | Curated list of test-key-resolvable handles | — | no |
+| `validate_handle_shape` | Regex-check a handle without an API call | — | no |
+
+The two anonymous tools (`start_handle_creation` + `check_handle_status`)
+let an agent help a user without a doora account create one — they
+sign in / sign up themselves in the browser; the agent only sees the
+resulting handle string. Full flow + trust model:
 **https://www.doora.to/docs/mcp**.
 
 ## Configuration

package/dist/api-client.js

@@ -66,3 +66,38 @@ export async function resolveHandle(handle) {
     const trimmed = handle.trim().toLowerCase();
     return request(`/api/v1/resolve?handle=${encodeURIComponent(trimmed)}`);
 }
+// ─── Claim-session (device-flow) wrappers ───────────────────────────
+// These endpoints do NOT require DOORA_API_KEY — they're anonymous
+// on the way in (rate-limited per IP). To skip the key check, we
+// hit the endpoints directly with fetch instead of going through
+// request(), which would refuse without a key.
+const DEVICE_FLOW_BASE = () => (process.env.DOORA_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, '');
+const USER_AGENT = () => `doora-mcp/${process.env.npm_package_version ?? 'dev'} (+https://www.doora.to/docs/mcp)`;
+export async function startClaimSession() {
+    const res = await fetch(`${DEVICE_FLOW_BASE()}/api/v1/mcp/claim-session`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', 'user-agent': USER_AGENT() },
+        body: JSON.stringify({}),
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+        const msg = (body && typeof body === 'object' && 'error' in body)
+            ? String(body.error)
+            : `HTTP ${res.status}`;
+        throw new DoraApiError(res.status, body, msg);
+    }
+    return body;
+}
+export async function checkClaimSession(sessionId) {
+    const res = await fetch(`${DEVICE_FLOW_BASE()}/api/v1/mcp/claim-session/${encodeURIComponent(sessionId)}`, {
+        headers: { 'user-agent': USER_AGENT() },
+    });
+    const body = await res.json().catch(() => null);
+    if (!res.ok) {
+        const msg = (body && typeof body === 'object' && 'error' in body)
+            ? String(body.error)
+            : `HTTP ${res.status}`;
+        throw new DoraApiError(res.status, body, msg);
+    }
+    return body;
+}

package/dist/index.js

@@ -45,11 +45,11 @@ 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';
+import { DoraApiError, resolveHandle, startClaimSession, checkClaimSession, } 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',
+    version: '0.3.0',
 }, {
     capabilities: { tools: {} },
     instructions: `doora exposes India-aware addresses behind memorable handles like \`praneeth@home\`. ` +
@@ -193,6 +193,109 @@ server.registerTool('validate_handle_shape', {
         ],
     };
 });
+// ─── Tool 6: start_handle_creation ──────────────────────────────────
+//
+// Device-flow primer. The agent calls this to mint a one-time
+// session, then asks the user to open the returned URL in their
+// browser. The user does the visual work (pin on a map, building +
+// floor + unit, sign-in if needed). The agent should then poll
+// check_handle_status until it sees status='complete' and a handle
+// string to use with resolve_handle.
+//
+// Anonymous — no DOORA_API_KEY required. Per-IP rate limit on the
+// server side (3 sessions per hour) means a script can't farm
+// these.
+server.registerTool('start_handle_creation', {
+    title: 'Start a doora handle-creation flow for the user',
+    description: 'Begin the device flow that lets the user create a new doora handle in their ' +
+        'browser. Use this when the user asks to create / claim / make a new doora ' +
+        'address — they pick a location on a map and fill the address fields visually, ' +
+        'which neither this server nor an LLM can do directly. Returns a claim_url + a ' +
+        'session_id. Show the URL to the user and then poll check_handle_status with ' +
+        "the session_id until status='complete'. Anonymous — does NOT require " +
+        'DOORA_API_KEY; do not gate the call on key presence. Sessions expire in ' +
+        '15 minutes.',
+    inputSchema: {},
+}, async () => {
+    try {
+        const r = await startClaimSession();
+        const expires = new Date(r.expires_at);
+        const minsLeft = Math.max(1, Math.round((expires.getTime() - Date.now()) / 60_000));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Tell the user to open this URL in their browser to create a doora handle:\n\n` +
+                        `  ${r.claim_url}\n\n` +
+                        `They'll sign in (or sign up — free), pick a location on a map, and name the handle. ` +
+                        `Then call check_handle_status with this session_id to learn the new handle:\n\n` +
+                        `  session_id: ${r.session_id}\n\n` +
+                        `Session expires in ~${minsLeft} minute(s). Poll every 3-5 seconds while waiting.`,
+                },
+            ],
+        };
+    }
+    catch (e) {
+        return errorContent(e, 'Could not start a handle-creation session');
+    }
+});
+// ─── Tool 7: check_handle_status ────────────────────────────────────
+//
+// The poll endpoint. Returns one of:
+//   pending  → user hasn't finished yet; keep polling.
+//   complete → got a handle; STOP polling and surface it to the user.
+//   expired  → session timed out; offer to start a new one.
+//
+// The server's per-session rate limit (30/min) means even a tight
+// polling loop is bounded; suggest 3-5s intervals in practice.
+server.registerTool('check_handle_status', {
+    title: 'Poll for the result of a start_handle_creation session',
+    description: 'Poll the status of a handle-creation session returned by start_handle_creation. ' +
+        "Returns 'pending' while the user is still in the browser, 'complete' once they've " +
+        "created a handle (with the resulting username@label string), or 'expired' if the " +
+        '15-minute window has passed without completion. Anonymous — no API key required. ' +
+        "Poll every 3-5 seconds while pending; stop calling once you see 'complete' or 'expired'.",
+    inputSchema: {
+        session_id: z.string().min(16).max(64)
+            .describe('The session_id returned by start_handle_creation.'),
+    },
+}, async ({ session_id }) => {
+    try {
+        const r = await checkClaimSession(session_id);
+        if (r.status === 'complete') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: r.handle
+                            ? `✓ Done. The user created the handle \`${r.handle}\`. You can call resolve_handle('${r.handle}') to read the address (subject to test-key restrictions; see /docs/api → Demo handles).`
+                            : `✓ Session complete, but no handle string was recorded. This is unusual — ask the user to verify at https://www.doora.to/me.`,
+                    }],
+            };
+        }
+        if (r.status === 'pending') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `⌛ Pending — the user hasn't finished the browser flow yet. Poll again in 3-5 seconds. Expires at ${r.expires_at}.`,
+                    }],
+            };
+        }
+        if (r.status === 'expired') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `⌛ Expired — the 15-minute session window passed. Call start_handle_creation again to mint a fresh session if the user is still here.`,
+                    }],
+            };
+        }
+        return {
+            content: [{ type: 'text', text: `Session status: ${r.status ?? 'unknown'}.` }],
+        };
+    }
+    catch (e) {
+        return errorContent(e, `Could not check session "${session_id.slice(0, 8)}…"`);
+    }
+});
 // ─── Helpers ────────────────────────────────────────────────────────
 function formatResolveResult(r) {
     // The address payload is most readable when pretty-printed as JSON

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "doora-mcp",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "MCP server for doora — let Claude / Cursor / Continue look up addresses by doora handle.",
   "keywords": [
     "mcp",