@limetry/mcp 0.0.0-stage → 1.2.49

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,54 @@
1
- # Temporary Holding Version
1
+ # `@limetry/mcp`
2
2
 
3
- 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.
3
+ MCP server for Limetry **agent action governance**: evaluate ActionIntents, record outcomes,
4
+ list privacy-safe audit events, and upsert action policies.
5
+
6
+ ## Quickstart
7
+
8
+ 1. Run a Limetry governance server (`yarn dev:server` from the monorepo root).
9
+ 2. Point the MCP host at this package with `LIMETRY_BEARER_TOKEN` and `LIMETRY_BASE_URL`.
10
+ 3. Ask the agent to call `limetry_evaluate` before irreversible tool calls; enforce deny in the loop.
11
+ 4. Call `limetry_record_action` after execute/skip/block.
12
+
13
+ > [!NOTE]
14
+ > Evaluate uses the **full** intent for policy matching. Audit stores a **privacy-safe record**
15
+ > (`audit_mode=minimal` by default). Do **not** put API keys, passwords, or chat transcripts in
16
+ > `metadata` / `details`. `limetry_record_action` runs client-side `redactDetails` before POST;
17
+ > the server also minimizes. See [Data minimization](https://limetry.org/docs/server/data-minimization).
18
+
19
+ ## Tools
20
+
21
+ | Tool | Purpose |
22
+ | --- | --- |
23
+ | `limetry_evaluate` | Allow / deny / wait + reasons + signed receipt |
24
+ | `limetry_record_action` | Scrubbed `action.recorded` event |
25
+ | `limetry_list_audit` | List recent privacy-safe audit rows |
26
+ | `limetry_upsert_policy` | Create/update ActionPolicy (`auditMode` supported) |
27
+
28
+ ## Run from source
29
+
30
+ `@limetry/mcp` may not be published to npm yet. From a checkout:
31
+
32
+ ```bash
33
+ yarn build:sdk && yarn workspace @limetry/mcp build
34
+ node packages/mcp/dist/index.js
35
+ ```
36
+
37
+ Cursor / Claude config example:
38
+
39
+ ```json
40
+ {
41
+ "mcpServers": {
42
+ "limetry": {
43
+ "command": "node",
44
+ "args": ["/absolute/path/to/limetry/packages/mcp/dist/index.js"],
45
+ "env": {
46
+ "LIMETRY_BEARER_TOKEN": "your-bearer-token",
47
+ "LIMETRY_BASE_URL": "http://localhost:3810"
48
+ }
49
+ }
50
+ }
51
+ }
52
+ ```
53
+
54
+ When the package is published, `npx -y @limetry/mcp` can replace the `node …/dist/index.js` command.
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Stdio MCP server exposing Limetry policy evaluation, action recording, audit,
4
+ * policy upsert, and approval tools (`\@limetry/mcp`).
5
+ *
6
+ * Requires `LIMETRY_API_KEY` (or `LIMETRY_BEARER_TOKEN`). Optional `LIMETRY_BASE_URL`
7
+ * defaults to `http://localhost:3810`.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ export {};
package/dist/index.js ADDED
@@ -0,0 +1,217 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Stdio MCP server exposing Limetry policy evaluation, action recording, audit,
4
+ * policy upsert, and approval tools (`\@limetry/mcp`).
5
+ *
6
+ * Requires `LIMETRY_API_KEY` (or `LIMETRY_BEARER_TOKEN`). Optional `LIMETRY_BASE_URL`
7
+ * defaults to `http://localhost:3810`.
8
+ *
9
+ * @packageDocumentation
10
+ */
11
+ import { randomUUID } from "node:crypto";
12
+ import { APP_VERSION, redactDetails } from "@limetry/sdk";
13
+ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
14
+ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
15
+ import { z } from "zod";
16
+ /**
17
+ * Limetry HTTP API origin with trailing slash stripped.
18
+ */
19
+ const BASE_URL = (process.env.LIMETRY_BASE_URL ?? "http://localhost:3810").replace(/\/$/, "");
20
+ /**
21
+ * Bearer token used for all Limetry API calls.
22
+ */
23
+ const API_KEY = process.env.LIMETRY_API_KEY ?? process.env.LIMETRY_BEARER_TOKEN ?? "";
24
+ if (!API_KEY) {
25
+ process.stderr.write("Error: LIMETRY_API_KEY environment variable is required.\n" +
26
+ "Run `limetry setup` or set LIMETRY_API_KEY / LIMETRY_BEARER_TOKEN in your MCP config.\n");
27
+ process.exit(1);
28
+ }
29
+ /**
30
+ * Sends a JSON request to the Limetry HTTP API.
31
+ *
32
+ * @param path - API path beginning with `/` (for example `/v1/policy/evaluate`).
33
+ * @param body - JSON-serializable request body (ignored for `GET`).
34
+ * @param method - HTTP method; defaults to `POST`.
35
+ * @returns Parsed JSON response body.
36
+ */
37
+ async function limetryFetch(path, body, method = "POST") {
38
+ const response = await fetch(`${BASE_URL}${path}`, {
39
+ method,
40
+ headers: {
41
+ "Authorization": `Bearer ${API_KEY}`,
42
+ "Content-Type": "application/json",
43
+ },
44
+ body: method === "GET" ? undefined : JSON.stringify(body),
45
+ });
46
+ return response.json();
47
+ }
48
+ /**
49
+ * Performs an authenticated GET against the Limetry HTTP API.
50
+ *
51
+ * @param path - API path beginning with `/`, including query string when needed.
52
+ * @returns Parsed JSON response body.
53
+ */
54
+ async function limetryGet(path) {
55
+ const response = await fetch(`${BASE_URL}${path}`, {
56
+ headers: { "Authorization": `Bearer ${API_KEY}` },
57
+ });
58
+ return response.json();
59
+ }
60
+ /**
61
+ * Zod schema for ActionIntent fields accepted by MCP tools.
62
+ * Missing `intent_id` / `issued_at` are filled at call time.
63
+ */
64
+ const actionIntentSchema = z.object({
65
+ intent_id: z.string().uuid().optional().describe("Defaults to a new UUID"),
66
+ policy_id: z.string().uuid().describe("Registered ActionPolicy id"),
67
+ agent_id: z.string().min(1).describe("Agent performing the action"),
68
+ action_type: z.string().min(1).describe("e.g. http_post, spend, email_send, deploy, delete"),
69
+ resource: z.string().min(1).describe("Target resource URL, path, or identifier"),
70
+ cost: z.object({
71
+ amount_minor: z.number().int().nonnegative(),
72
+ currency: z.string().min(3),
73
+ }).optional().describe("Optional cost for spend-like actions"),
74
+ metadata: z.record(z.string(), z.string()).optional(),
75
+ issued_at: z.string().datetime().optional(),
76
+ nonce: z.union([z.string(), z.number()]).optional(),
77
+ });
78
+ /**
79
+ * MCP server instance registered with Limetry governance tools.
80
+ */
81
+ const server = new McpServer({
82
+ name: "limetry",
83
+ version: APP_VERSION,
84
+ });
85
+ server.tool("limetry_evaluate", "Evaluate an agent action intent against a Limetry action policy. " +
86
+ "Returns allow, deny, or approval_required, reasons, a signed decision receipt, and writes an audit event. " +
87
+ "Call this before irreversible or expensive tool calls (HTTP POST, deploy, delete, email, SQL write). " +
88
+ "Send only fields needed for policy — avoid embedding API keys or chat transcripts in metadata.", {
89
+ tenant_id: z.string().default("default"),
90
+ policy_id: z.string().uuid().optional().describe("Overrides intent.policy_id when set"),
91
+ intent: actionIntentSchema,
92
+ }, async ({ tenant_id, policy_id, intent }) => {
93
+ const resolvedPolicyId = policy_id ?? intent.policy_id;
94
+ const payload = {
95
+ tenant_id,
96
+ policy_id: resolvedPolicyId,
97
+ intent: {
98
+ ...intent,
99
+ intent_id: intent.intent_id ?? randomUUID(),
100
+ policy_id: resolvedPolicyId,
101
+ issued_at: intent.issued_at ?? new Date().toISOString(),
102
+ },
103
+ };
104
+ const result = await limetryFetch("/v1/policy/evaluate", payload);
105
+ return {
106
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
107
+ };
108
+ });
109
+ server.tool("limetry_record_action", "Record that an agent executed, skipped, or was blocked from an action after evaluation. " +
110
+ "Writes a structured action.recorded audit/telemetry event. " +
111
+ "Do not put secrets, tokens, or full chat transcripts in details — the server redacts known " +
112
+ "secret keys, and default audit_mode=minimal drops the details bag from storage.", {
113
+ tenant_id: z.string().default("default"),
114
+ intent: actionIntentSchema,
115
+ decision_id: z.string().optional().describe("Decision id from limetry_evaluate"),
116
+ outcome: z.enum(["executed", "skipped", "blocked"]),
117
+ details: z.record(z.string(), z.unknown()).optional(),
118
+ }, async ({ tenant_id, intent, decision_id, outcome, details }) => {
119
+ const result = await limetryFetch("/v1/actions/record", {
120
+ tenant_id,
121
+ intent: {
122
+ ...intent,
123
+ intent_id: intent.intent_id ?? randomUUID(),
124
+ issued_at: intent.issued_at ?? new Date().toISOString(),
125
+ },
126
+ decision_id,
127
+ outcome,
128
+ details: redactDetails(details),
129
+ });
130
+ return {
131
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
132
+ };
133
+ });
134
+ server.tool("limetry_list_audit", "List recent Limetry audit/telemetry events (policy evaluations and recorded actions).", {
135
+ limit: z.number().int().positive().max(200).default(50),
136
+ event_type: z.string().optional().describe("e.g. policy.evaluated, action.recorded"),
137
+ agent_id: z.string().optional(),
138
+ cursor: z.string().optional(),
139
+ }, async ({ limit, event_type, agent_id, cursor }) => {
140
+ const params = new URLSearchParams();
141
+ params.set("limit", String(limit));
142
+ if (event_type)
143
+ params.set("event_type", event_type);
144
+ if (agent_id)
145
+ params.set("agent_id", agent_id);
146
+ if (cursor)
147
+ params.set("cursor", cursor);
148
+ const result = await limetryGet(`/v1/audit?${params.toString()}`);
149
+ return {
150
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
151
+ };
152
+ });
153
+ server.tool("limetry_upsert_policy", "Create or update an ActionPolicy (allowed/denied action types, resource patterns, optional cost cap).", {
154
+ tenant_id: z.string().default("default"),
155
+ agent_id: z.string().describe("Agent id bound to the policy, or * for any"),
156
+ allowed_action_types: z.array(z.string()).describe("Allowlist of action types"),
157
+ denied_action_types: z.array(z.string()).optional(),
158
+ allowed_resource_patterns: z.array(z.string()).optional().describe("Prefix or glob patterns"),
159
+ blocked_resource_patterns: z.array(z.string()).optional(),
160
+ max_cost_minor: z.number().int().nonnegative().optional().describe("Max cost in minor units"),
161
+ currency: z.string().default("USD"),
162
+ policy_id: z.string().uuid().optional(),
163
+ }, async (input) => {
164
+ const { createSlimActionPolicy } = await import("@limetry/sdk");
165
+ const policy = createSlimActionPolicy({
166
+ agentId: input.agent_id,
167
+ organizationId: input.tenant_id,
168
+ allowedActionTypes: input.allowed_action_types,
169
+ deniedActionTypes: input.denied_action_types,
170
+ allowedResourcePatterns: input.allowed_resource_patterns,
171
+ blockedResourcePatterns: input.blocked_resource_patterns,
172
+ maxCostMinor: input.max_cost_minor,
173
+ currency: input.currency,
174
+ policyId: input.policy_id,
175
+ });
176
+ const result = await limetryFetch(`/v1/policies/${policy.policy_id}`, { tenant_id: input.tenant_id, policy }, "PUT");
177
+ return {
178
+ content: [{ type: "text", text: JSON.stringify({ ...result, policy_id: policy.policy_id }, null, 2) }],
179
+ };
180
+ });
181
+ server.tool("limetry_list_approvals", "List pending (or filtered) Limetry approvals that require a human reviewer.", {
182
+ status: z.enum(["pending", "approved", "denied", "all"]).default("pending"),
183
+ }, async ({ status }) => {
184
+ const result = await limetryGet(`/v1/approvals?status=${encodeURIComponent(status)}`);
185
+ return {
186
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
187
+ };
188
+ });
189
+ server.tool("limetry_resolve_approval", "Approve or deny a pending approval. When approving, pass the exact ActionIntent so the " +
190
+ "server can verify the payload hash before marking the approval approved.", {
191
+ approval_id: z.string().uuid(),
192
+ decision: z.enum(["approve", "deny"]),
193
+ reviewer: z.string().default("mcp-operator"),
194
+ intent: actionIntentSchema.optional().describe("Required for approve when payload-hash binding is enforced"),
195
+ }, async ({ approval_id, decision, reviewer, intent }) => {
196
+ const path = decision === "approve"
197
+ ? `/v1/approvals/${approval_id}/approve`
198
+ : `/v1/approvals/${approval_id}/deny`;
199
+ const result = await limetryFetch(path, {
200
+ reviewer,
201
+ intent: intent
202
+ ? {
203
+ ...intent,
204
+ intent_id: intent.intent_id ?? randomUUID(),
205
+ issued_at: intent.issued_at ?? new Date().toISOString(),
206
+ }
207
+ : undefined,
208
+ });
209
+ return {
210
+ content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
211
+ };
212
+ });
213
+ /**
214
+ * Stdio transport that connects the MCP server to the host process.
215
+ */
216
+ const transport = new StdioServerTransport();
217
+ await server.connect(transport);
package/package.json CHANGED
@@ -1,6 +1,43 @@
1
1
  {
2
2
  "name": "@limetry/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.2.49",
4
+ "description": "MCP server for Limetry agent action governance and telemetry",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "bin": {
8
+ "limetry-mcp": "dist/index.js"
9
+ },
10
+ "main": "./dist/index.js",
11
+ "files": [
12
+ "dist"
13
+ ],
14
+ "publishConfig": {
15
+ "access": "public",
16
+ "registry": "https://registry.npmjs.org"
17
+ },
18
+ "repository": {
19
+ "type": "git",
20
+ "url": "git+https://github.com/limetry/limetry.git",
21
+ "directory": "packages/mcp"
22
+ },
23
+ "scripts": {
24
+ "prepack": "node ../../scripts/rewrite-workspace-protocol.mjs prepare",
25
+ "postpack": "node ../../scripts/rewrite-workspace-protocol.mjs restore",
26
+ "build": "tsc",
27
+ "dev": "tsc --watch",
28
+ "start": "node dist/index.js",
29
+ "typecheck": "tsgo -p tsconfig.json --noEmit"
30
+ },
31
+ "dependencies": {
32
+ "@limetry/sdk": "^1.2.49",
33
+ "@modelcontextprotocol/sdk": "^1.30.0",
34
+ "zod": "^4.5.4"
35
+ },
36
+ "devDependencies": {
37
+ "@types/node": "^22.20.2",
38
+ "typescript": "^5.8.2"
39
+ },
40
+ "engines": {
41
+ "node": ">=20"
42
+ }
43
+ }