@getpalmos/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PalmOS
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,103 @@
+# @getpalmos/mcp
+
+Model Context Protocol (MCP) server for PalmOS. It gives Claude Code, Codex, and
+any other MCP-capable agent a set of **governed payment tools** — the agent can
+discover paid services, check policy, and request payments, while PalmOS enforces
+budget, allowlist, approval, settlement, and audit rules server-side. The agent
+never holds a wallet key.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `palmos_list_services` | List the paid services this agent is allowed to call. |
+| `palmos_check_policy` | Preview whether a payment would be allowed / approval-gated / denied (no spend). |
+| `palmos_get_agent_status` | Report the agent's PalmOS identity, trust tier, and settlement mode. |
+| `palmos_pay` | Execute a governed paid-service call. |
+
+`palmos_pay` is the only tool that can move money, and every call is still
+gated by PalmOS policy: small allowed payments execute, higher-value ones become
+approval-pending for an operator, and disallowed services are blocked.
+
+## Prerequisites
+
+1. A running PalmOS backend (defaults to the hosted API `https://api.getpalmos.xyz`).
+2. An agent created in the PalmOS dashboard with an issued SDK credential
+   (`palmos_...` token).
+
+## Configure
+
+The server reads two environment variables:
+
+- `PALMOS_AGENT_TOKEN` (required) — the issued `palmos_...` SDK credential.
+- `PALMOS_API_URL` (optional) — defaults to the hosted API; set it only for a
+  self-hosted backend.
+
+### Claude Code
+
+```bash
+claude mcp add palmos --env PALMOS_AGENT_TOKEN=palmos_YOUR_TOKEN -- npx -y @getpalmos/mcp
+```
+
+or add it to `.mcp.json` / your Claude Code MCP config directly:
+
+```json
+{
+  "mcpServers": {
+    "palmos": {
+      "command": "npx",
+      "args": ["-y", "@getpalmos/mcp"],
+      "env": {
+        "PALMOS_AGENT_TOKEN": "palmos_YOUR_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### Codex
+
+In `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.palmos]
+command = "npx"
+args = ["-y", "@getpalmos/mcp"]
+env = { PALMOS_AGENT_TOKEN = "palmos_YOUR_TOKEN" }
+```
+
+### Local (before publishing / for development)
+
+Point the runner at the built file in this repo instead of `npx`:
+
+```json
+{
+  "mcpServers": {
+    "palmos": {
+      "command": "node",
+      "args": ["/absolute/path/to/palmos/packages/mcp/dist/index.js"],
+      "env": { "PALMOS_AGENT_TOKEN": "palmos_YOUR_TOKEN" }
+    }
+  }
+}
+```
+
+Build it first with `npm run build` (from `packages/mcp`) or
+`npm run package:mcp:build` from the repo root.
+
+## Use
+
+Once configured, ask the agent naturally, e.g.:
+
+> "List my PalmOS services, check the policy for `local.pusd.spot_price`, then
+> pay for a BTC/USD spot price."
+
+The agent will call `palmos_list_services` → `palmos_check_policy` → `palmos_pay`.
+PalmOS records every outcome (executed, approval-pending, blocked) with an audit
+trail in the dashboard.
+
+## Token storage
+
+Treat `PALMOS_AGENT_TOKEN` like a payment credential: keep it in your MCP client's
+secret/env config, not in source control, use a separate credential per runtime,
+and rotate or revoke it from the PalmOS dashboard if it may have been exposed.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}

package/dist/index.js

@@ -0,0 +1,123 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { PalmosAgentClient, PalmosAgentClientError } from '@getpalmos/agent';
+// Lazily build the client so the server can start and advertise its tools even
+// when no credential is set yet. Tool *calls* still require PALMOS_AGENT_TOKEN.
+let client;
+function getClient() {
+    if (client) {
+        return client;
+    }
+    const token = process.env.PALMOS_AGENT_TOKEN?.trim();
+    if (!token) {
+        throw new Error('Set PALMOS_AGENT_TOKEN to an issued palmos_... SDK credential (from the PalmOS dashboard).');
+    }
+    client = new PalmosAgentClient({
+        baseUrl: process.env.PALMOS_API_URL?.trim(),
+        token,
+    });
+    return client;
+}
+function ok(data) {
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+}
+function fail(error) {
+    const message = error instanceof PalmosAgentClientError
+        ? `PalmOS API error ${error.status}: ${error.message}`
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return { isError: true, content: [{ type: 'text', text: message }] };
+}
+const server = new McpServer({ name: 'palmos', version: '0.1.0' });
+server.registerTool('palmos_list_services', {
+    title: 'List PalmOS paid services',
+    description: 'List the paid services this PalmOS agent is allowed to call, with vendor, settlement asset, expected amount, payment rail, and whether each is currently allowed by policy. Call this first to discover valid serviceId values.',
+    inputSchema: {},
+}, async () => {
+    try {
+        return ok(await getClient().listServices());
+    }
+    catch (error) {
+        return fail(error);
+    }
+});
+server.registerTool('palmos_get_agent_status', {
+    title: 'Get PalmOS agent status',
+    description: "Return this agent's PalmOS identity and posture: agent and credential status, trust tier, settlement mode, and wallet state.",
+    inputSchema: {},
+}, async () => {
+    try {
+        return ok(await getClient().getAgentStatus());
+    }
+    catch (error) {
+        return fail(error);
+    }
+});
+server.registerTool('palmos_check_policy', {
+    title: 'Check PalmOS payment policy',
+    description: 'Preview whether a payment for a service (and optional amount) would be allowed, approval-gated, or denied — WITHOUT spending anything. Use this before palmos_pay to avoid surprises.',
+    inputSchema: {
+        serviceId: z
+            .string()
+            .describe('PalmOS service id, e.g. local.pusd.spot_price'),
+        amount: z
+            .string()
+            .optional()
+            .describe('Optional amount override as a decimal string, e.g. "0.25".'),
+    },
+}, async ({ serviceId, amount }) => {
+    try {
+        return ok(await getClient().checkPolicy({ serviceId, amount }));
+    }
+    catch (error) {
+        return fail(error);
+    }
+});
+server.registerTool('palmos_pay', {
+    title: 'Execute a governed PalmOS payment',
+    description: 'Request a governed paid-service call. PalmOS enforces policy, session budget, vendor allowlist, and approval gates server-side: small allowed payments execute immediately, higher-value ones become approval-pending for an operator, and disallowed services/vendors are blocked. The agent never holds wallet keys. Returns the execution record; check result.kind (executed | approval_pending | waiting_for_execution | blocked | execution_failed). Pass a stable idempotencyKey derived from a job/run id so retries do not double-pay.',
+    inputSchema: {
+        serviceId: z.string().describe('PalmOS service id to pay for.'),
+        request: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe('Service request payload, e.g. { "base": "BTC", "quote": "USD" }.'),
+        amount: z
+            .string()
+            .optional()
+            .describe('Optional amount override as a decimal string.'),
+        note: z
+            .string()
+            .optional()
+            .describe('Optional human-readable note stored on the paid-call record.'),
+        idempotencyKey: z
+            .string()
+            .optional()
+            .describe('Stable key from a job/run id so retries are not double-charged.'),
+        privacy: z
+            .enum(['default', 'required'])
+            .optional()
+            .describe('Set "required" to force private (Umbra) settlement; fails closed if no private route is configured.'),
+    },
+}, async (input) => {
+    try {
+        return ok(await getClient().pay(input));
+    }
+    catch (error) {
+        return fail(error);
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stdout is the JSON-RPC channel; log to stderr only.
+    console.error('[palmos-mcp] PalmOS MCP server ready on stdio.');
+}
+main().catch((error) => {
+    console.error('[palmos-mcp] fatal:', error instanceof Error ? error.message : error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@getpalmos/mcp",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server for PalmOS. Gives Claude Code, Codex, and other MCP agents governed PUSD payment tools.",
+  "type": "module",
+  "license": "MIT",
+  "author": "PalmOS",
+  "homepage": "https://www.getpalmos.xyz",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Pavilion-devs/palmos.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Pavilion-devs/palmos/issues"
+  },
+  "bin": {
+    "palmos-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "palmos",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "pusd",
+    "solana",
+    "payments",
+    "claude",
+    "codex"
+  ],
+  "dependencies": {
+    "@getpalmos/agent": "^0.1.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2"
+  }
+}