@conciergeprotocol/mcp 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,45 @@
-# Temporary Holding Version
+# @conciergeprotocol/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server that asks a [Concierge Agent Protocol](https://conciergeprotocol.org) front door. Claude, Cursor, and other MCP hosts get three tools. The company publishes `agent.txt`. This package calls it.
+
+The protocol is at [conciergeprotocol.org](https://conciergeprotocol.org). Source is at [github.com/conciergeprotocol/js](https://github.com/conciergeprotocol/js). The library underneath is [@conciergeprotocol/client](https://www.npmjs.com/package/@conciergeprotocol/client).
+
+## Install
+
+```sh
+npm install @conciergeprotocol/mcp
+```
+
+Or run it without a global install. Cursor, Claude Desktop, and VS Code use the same block. In VS Code it goes in `.vscode/mcp.json`. In Cursor and Claude Desktop it goes in the MCP settings file.
+
+```json
+{
+  "mcpServers": {
+    "cap": {
+      "command": "npx",
+      "args": ["-y", "@conciergeprotocol/mcp"],
+      "env": { "CAP_FROM": "agent:my-assistant" }
+    }
+  }
+}
+```
+
+`CAP_FROM` names the caller. It must look like `agent:my-assistant`. When it is unset, the server uses `agent:cap-mcp`.
+
+Node.js 18 or newer.
+
+## Tools
+
+| Tool | What it does |
+| --- | --- |
+| `cap_discover` | Reads `agent.txt` and reports whether the domain has a front door. |
+| `cap_ask` | Sends one question and waits up to 60 seconds. |
+| `cap_check` | Reads a message that was still `working`. |
+
+`cap_ask` sends only the new question. Pass the previous message id for a follow-up. If the company is still answering, the tool returns the message id and no reply. Call `cap_check`. Do not guess the answer.
+
+A domain with no `agent.txt` comes back as a normal result, which is the signal to browse the site.
+
+## License
+
+Apache 2.0

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@conciergeprotocol/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "MCP server for asking a Concierge Agent Protocol front door.",
+  "type": "module",
+  "bin": {
+    "cap-mcp": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "Apache-2.0",
+  "homepage": "https://conciergeprotocol.org",
+  "keywords": [
+    "concierge",
+    "cap",
+    "mcp",
+    "agents",
+    "model-context-protocol"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conciergeprotocol/js.git",
+    "directory": "packages/mcp"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@conciergeprotocol/client": "workspace:*",
+    "@modelcontextprotocol/sdk": "1.32.1",
+    "zod": "^4.6.7"
+  }
+}

package/src/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+import { createClient } from '@conciergeprotocol/client'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import * as z from 'zod/v4'
+import { createTools, toolError } from './tools.js'
+
+const FROM = /^agent:[A-Za-z0-9_.-]{1,64}$/
+const from = process.env.CAP_FROM || 'agent:cap-mcp'
+if (!FROM.test(from)) {
+  console.error('CAP_FROM must be agent:{id}.')
+  process.exit(1)
+}
+
+const ASK = [
+  'Ask a company that publishes a CAP front door.',
+  'Use this when the person asks about a specific company, product, store, or organization with a known website. Prefer it to browsing when the site has a front door.',
+  'Send only the new question in a follow-up, with conversation_id.',
+  'Never write an answer for the site while it is still answering.',
+  'The reply is the site\'s own framing. For comparisons and reviews, check other sources too.',
+  'Never put the person\'s password or another site\'s data in context.',
+].join(' ')
+
+const tools = createTools(createClient({ from, maxWaitMs: 60_000 }))
+
+function ok(value) {
+  return { content: [{ type: 'text', text: JSON.stringify(value) }] }
+}
+
+function fail(err) {
+  return { isError: true, content: [{ type: 'text', text: toolError(err) }] }
+}
+
+const server = new McpServer({ name: 'cap', version: '0.1.0' })
+
+server.registerTool('cap_discover', {
+  description: 'Check whether a website has a CAP front door, and whether visitors can log in.',
+  inputSchema: { domain: z.string().describe('The company domain, such as cosmicjs.com') },
+}, async (args) => {
+  try {
+    return ok(await tools.cap_discover(args))
+  } catch (err) {
+    return fail(err)
+  }
+})
+
+server.registerTool('cap_ask', {
+  description: ASK,
+  inputSchema: {
+    domain: z.string().describe('The company domain, such as cosmicjs.com'),
+    message: z.string().describe('The question to send. On a follow-up, send only the new question.'),
+    context: z.record(z.string(), z.unknown()).optional().describe('A short brief such as sizes, dates, or style. Not a profile.'),
+    conversation_id: z.string().optional().describe('The conversation_id from the previous cap_ask, when this continues that conversation.'),
+  },
+}, async (args) => {
+  try {
+    return ok(await tools.cap_ask(args))
+  } catch (err) {
+    return fail(err)
+  }
+})
+
+server.registerTool('cap_check', {
+  description: 'Read a CAP message that was still being answered. Do not guess a reply while the status is working.',
+  inputSchema: {
+    domain: z.string().describe('The company domain used in cap_ask'),
+    message_id: z.string().describe('The message_id returned by cap_ask'),
+  },
+}, async (args) => {
+  try {
+    return ok(await tools.cap_check(args))
+  } catch (err) {
+    return fail(err)
+  }
+})
+
+const transport = new StdioServerTransport()
+await server.connect(transport)

package/src/tools.js

@@ -0,0 +1,58 @@
+import { CapError, NoDoorError } from '@conciergeprotocol/client'
+
+const ASK_HINT = 'The company is still answering. Call cap_check with this message_id. Do not write a reply for the company.'
+
+export function createTools(cap) {
+  return {
+    async cap_discover({ domain }) {
+      const door = await cap.discover(domain)
+      if (!door) return { door: false }
+      return {
+        door: true,
+        name: door.name,
+        chat: door.chat,
+        login: Boolean(door.oauth),
+      }
+    },
+
+    async cap_ask({ domain, message, context, conversation_id }) {
+      try {
+        const answer = await cap.ask(domain, message, {
+          context,
+          previousMessageId: conversation_id,
+        })
+        if (answer.status === 'working') {
+          return {
+            status: 'working',
+            message_id: answer.id,
+            conversation_id: answer.id,
+            message: ASK_HINT,
+          }
+        }
+        if (answer.status === 'failed') {
+          return { status: 'failed', error: answer.error, conversation_id: answer.id }
+        }
+        return { status: 'done', reply: answer.reply, conversation_id: answer.id }
+      } catch (err) {
+        if (err instanceof NoDoorError) {
+          return { door: false, message: `${domain} has no CAP front door. Browse the site instead.` }
+        }
+        throw err
+      }
+    },
+
+    async cap_check({ domain, message_id }) {
+      const answer = await cap.get(domain, message_id)
+      if (answer.status === 'working') {
+        return { status: 'working', message_id: answer.id, message: ASK_HINT }
+      }
+      if (answer.status === 'failed') return { status: 'failed', error: answer.error, message_id: answer.id }
+      return { status: 'done', reply: answer.reply, message_id: answer.id }
+    },
+  }
+}
+
+export function toolError(err) {
+  if (err instanceof CapError) return err.message
+  return 'The front door could not be reached.'
+}