@madezmedia/acmi-mcp 1.3.0 → 1.4.0
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 +372 -69
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,12 +1,26 @@
|
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://v3b.fal.media/files/b/0a98cb49/ns7vLT2QV8YBH1LTtzSXr.jpg" alt="ACMI Protocol Hero" width="800">
|
|
3
|
+
</p>
|
|
4
|
+
|
|
1
5
|
# @madezmedia/acmi-mcp
|
|
2
6
|
|
|
3
|
-
> **Persistent agent memory in any MCP host.** A drop-in Model Context Protocol server that gives Claude Desktop, Cursor, Cline, Windsurf — or any MCP-compatible AI tool — direct read/write access to **ACMI** (Agentic Context
|
|
7
|
+
> **Persistent agent memory in any MCP host.** A drop-in Model Context Protocol server that gives Claude Desktop, Cursor, Cline, Windsurf — or any MCP-compatible AI tool — direct read/write access to **ACMI** (Agentic Context Memory Interface) on Upstash Redis.
|
|
4
8
|
|
|
5
9
|
[](https://www.npmjs.com/package/@madezmedia/acmi-mcp)
|
|
10
|
+
[](https://github.com/madezmedia/acmi/blob/main/SPEC.md)
|
|
6
11
|
[](./LICENSE)
|
|
7
12
|
[](https://nodejs.org)
|
|
13
|
+
[](#the-16-tools)
|
|
14
|
+
|
|
15
|
+
ACMI is the **three-key protocol for agent memory**: every entity stores exactly three things an LLM needs to make decisions — a **Profile** (who/what), **Signals** (current state), and a **Timeline** (event log). This MCP package exposes 16 tools that wrap that model so any LLM tool can persist, retrieve, and coordinate across sessions, agents, and surfaces — no SQL joins, no schema migrations, no token bloat.
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
Profile → who (identity, preferences — stable)
|
|
19
|
+
Signals → now (current state — what's open, what's pending)
|
|
20
|
+
Timeline → then (append-only event log of everything that happened)
|
|
21
|
+
```
|
|
8
22
|
|
|
9
|
-
|
|
23
|
+
That's it. No vector index. No knowledge graph. No fact-extraction pass. Three keys per entity, stored in the simplest data store on earth.
|
|
10
24
|
|
|
11
25
|
---
|
|
12
26
|
|
|
@@ -15,137 +29,426 @@ ACMI is the **three-key protocol for agent memory**: every entity has a Profile
|
|
|
15
29
|
LLM tools are stateless by default. Every conversation starts cold; agents can't remember decisions, share context with siblings, or pick up where they left off. ACMI fixes that with a single Redis-backed primitive (Profile + Signals + Timeline per entity), and this package makes it accessible to any MCP host with one config line.
|
|
16
30
|
|
|
17
31
|
**You get:**
|
|
18
|
-
- Cross-session memory that survives restarts, model swaps, and tool changes.
|
|
19
|
-
- Multi-agent coordination — Claude, Cursor, Cline, your custom agents all reading/writing the same store.
|
|
20
|
-
- Real-time event timelines with correlation tracking, so you can answer "what did Agent X decide about Project Y last Tuesday?" in one query.
|
|
21
|
-
-
|
|
32
|
+
- **Cross-session memory** that survives restarts, model swaps, and tool changes.
|
|
33
|
+
- **Multi-agent coordination** — Claude, Cursor, Cline, your custom agents all reading/writing the same store.
|
|
34
|
+
- **Real-time event timelines** with correlation tracking, so you can answer *"what did Agent X decide about Project Y last Tuesday?"* in one query.
|
|
35
|
+
- **Work item tracking** with separate profile/signal/timeline keys per work item (deals, tickets, projects, sprints).
|
|
36
|
+
- **Thread-based fan-out** so agents broadcasting a `coord-broadcast` event reach every subscriber on `thread:agent-coordination` without N×M wiring.
|
|
37
|
+
- **Built-in safety guards** that refuse to mutate protected registry keys, reject malformed segments, and enforce dry-run-then-confirm on every destructive operation.
|
|
22
38
|
|
|
23
39
|
---
|
|
24
40
|
|
|
25
41
|
## Install
|
|
26
42
|
|
|
43
|
+
### Global install (recommended for daily use)
|
|
44
|
+
|
|
27
45
|
```bash
|
|
28
46
|
npm install -g @madezmedia/acmi-mcp
|
|
29
47
|
```
|
|
30
48
|
|
|
31
|
-
|
|
49
|
+
Then point your MCP host at the `acmi-mcp` binary (config snippets below).
|
|
50
|
+
|
|
51
|
+
### Zero-install via npx
|
|
32
52
|
|
|
33
53
|
```bash
|
|
34
|
-
|
|
35
|
-
export UPSTASH_REDIS_REST_TOKEN="your-token"
|
|
54
|
+
npx -y @madezmedia/acmi-mcp
|
|
36
55
|
```
|
|
37
56
|
|
|
38
|
-
|
|
57
|
+
Useful for one-off testing or for hosts (like Claude Desktop / Smithery) that prefer ephemeral execution.
|
|
58
|
+
|
|
59
|
+
### Requirements
|
|
60
|
+
|
|
61
|
+
- Node.js 18+
|
|
62
|
+
- An Upstash Redis REST endpoint + token (free tier works fine — [upstash.com](https://upstash.com))
|
|
39
63
|
|
|
40
64
|
---
|
|
41
65
|
|
|
42
|
-
##
|
|
66
|
+
## Quick start
|
|
67
|
+
|
|
68
|
+
### 1. Get Upstash credentials
|
|
43
69
|
|
|
44
|
-
|
|
70
|
+
Create a free Redis database at [console.upstash.com](https://console.upstash.com). Copy:
|
|
71
|
+
- `UPSTASH_REDIS_REST_URL` (e.g. `https://yourthing-12345.upstash.io`)
|
|
72
|
+
- `UPSTASH_REDIS_REST_TOKEN` (long token starting with `gQAAAAAAAZ...`)
|
|
45
73
|
|
|
46
|
-
|
|
74
|
+
### 2. Add to your MCP host
|
|
75
|
+
|
|
76
|
+
#### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)
|
|
47
77
|
|
|
48
78
|
```json
|
|
49
79
|
{
|
|
50
80
|
"mcpServers": {
|
|
51
81
|
"acmi": {
|
|
52
|
-
"command": "
|
|
82
|
+
"command": "npx",
|
|
83
|
+
"args": ["-y", "@madezmedia/acmi-mcp"],
|
|
53
84
|
"env": {
|
|
54
|
-
"UPSTASH_REDIS_REST_URL": "https://
|
|
55
|
-
"UPSTASH_REDIS_REST_TOKEN": "
|
|
85
|
+
"UPSTASH_REDIS_REST_URL": "https://yourthing-12345.upstash.io",
|
|
86
|
+
"UPSTASH_REDIS_REST_TOKEN": "gQAAAAAAAZ..."
|
|
56
87
|
}
|
|
57
88
|
}
|
|
58
89
|
}
|
|
59
90
|
}
|
|
60
91
|
```
|
|
61
92
|
|
|
62
|
-
Restart Claude Desktop. You
|
|
63
|
-
|
|
64
|
-
### Cursor
|
|
93
|
+
Restart Claude Desktop. You should now see 16 ACMI tools available.
|
|
65
94
|
|
|
66
|
-
|
|
95
|
+
#### Cursor (`~/.cursor/mcp.json`)
|
|
67
96
|
|
|
68
97
|
```json
|
|
69
98
|
{
|
|
70
|
-
"
|
|
71
|
-
"
|
|
72
|
-
|
|
73
|
-
"
|
|
74
|
-
"
|
|
99
|
+
"mcpServers": {
|
|
100
|
+
"acmi": {
|
|
101
|
+
"command": "npx",
|
|
102
|
+
"args": ["-y", "@madezmedia/acmi-mcp"],
|
|
103
|
+
"env": {
|
|
104
|
+
"UPSTASH_REDIS_REST_URL": "https://yourthing-12345.upstash.io",
|
|
105
|
+
"UPSTASH_REDIS_REST_TOKEN": "gQAAAAAAAZ..."
|
|
106
|
+
}
|
|
75
107
|
}
|
|
76
108
|
}
|
|
77
109
|
}
|
|
78
110
|
```
|
|
79
111
|
|
|
80
|
-
|
|
112
|
+
#### Cline / Windsurf
|
|
113
|
+
|
|
114
|
+
Both follow the standard MCP `mcpServers` config — same shape as above. Drop the snippet into the tool's MCP config file and restart.
|
|
115
|
+
|
|
116
|
+
#### Smithery (hosted, no local install)
|
|
117
|
+
|
|
118
|
+
Browse to [smithery.ai/@madezmediapartners/acmi-mcp](https://smithery.ai/@madezmediapartners/acmi-mcp), paste your Upstash credentials, and Smithery hosts the MCP server for you. Useful for Claude Web / Claude.ai Cloud Agents where local stdio servers don't apply.
|
|
81
119
|
|
|
82
|
-
|
|
120
|
+
### 3. Bootstrap a session
|
|
121
|
+
|
|
122
|
+
In any MCP host with ACMI connected, ask:
|
|
123
|
+
|
|
124
|
+
> *"Bootstrap me as agent `my-agent`."*
|
|
125
|
+
|
|
126
|
+
The agent will call `acmi_bootstrap` and get back a single JSON payload with the agent's profile, signals, active work items, recent timeline, and last rollup — everything needed to resume work with full context.
|
|
83
127
|
|
|
84
128
|
---
|
|
85
129
|
|
|
86
130
|
## The 16 tools
|
|
87
131
|
|
|
88
|
-
|
|
|
89
|
-
|
|
90
|
-
| `acmi_profile` |
|
|
91
|
-
| `acmi_signal` |
|
|
92
|
-
| `acmi_event` |
|
|
93
|
-
| `acmi_get` |
|
|
94
|
-
| `acmi_list` | List
|
|
95
|
-
| `acmi_work_create` | Create a work item (
|
|
96
|
-
| `acmi_work_event` |
|
|
97
|
-
| `acmi_work_signal` | Update
|
|
98
|
-
| `acmi_work_get` | Read a work item's full context
|
|
99
|
-
| `acmi_work_list` | List all work item IDs |
|
|
100
|
-
| `acmi_cat` | Multi-stream merge
|
|
101
|
-
| `acmi_spawn` |
|
|
102
|
-
| `acmi_bootstrap` | One-shot agent context bundle
|
|
103
|
-
| `acmi_active` |
|
|
104
|
-
| `acmi_rollup_set` | Set
|
|
105
|
-
| `acmi_delete` |
|
|
132
|
+
| # | Tool | Purpose |
|
|
133
|
+
|---|---|---|
|
|
134
|
+
| 1 | `acmi_profile` | Set or read an entity's profile (who/what — stable identity + metadata) |
|
|
135
|
+
| 2 | `acmi_signal` | Set or read current signals (state flags, status, current focus) |
|
|
136
|
+
| 3 | `acmi_event` | Append a timeline event (the workhorse — logs every meaningful action) |
|
|
137
|
+
| 4 | `acmi_get` | Generic GET for any ACMI key (escape hatch when you know what you want) |
|
|
138
|
+
| 5 | `acmi_list` | List entity IDs in a namespace (e.g. all `agent:*` or all `work:*`) |
|
|
139
|
+
| 6 | `acmi_work_create` | Create a work item (deal, ticket, project, sprint) with profile + initial signals |
|
|
140
|
+
| 7 | `acmi_work_event` | Append progress event to a work item's timeline |
|
|
141
|
+
| 8 | `acmi_work_signal` | Update a work item's signals (status, progress, blockers) |
|
|
142
|
+
| 9 | `acmi_work_get` | Read a work item's full context: profile + signals + timeline + sessions |
|
|
143
|
+
| 10 | `acmi_work_list` | List all work item IDs |
|
|
144
|
+
| 11 | `acmi_cat` | Multi-stream event merge across multiple timelines, sorted by timestamp |
|
|
145
|
+
| 12 | `acmi_spawn` | Register a new agent session (model + session_id + agent_id) |
|
|
146
|
+
| 13 | `acmi_bootstrap` | One-shot agent context bundle (profile + signals + active + rollup + recent timeline) |
|
|
147
|
+
| 14 | `acmi_active` | Manage which threads/work items an agent is actively engaged with |
|
|
148
|
+
| 15 | `acmi_rollup_set` | Set the agent's `rollup:latest` pointer (read by next session's bootstrap) |
|
|
149
|
+
| 16 | `acmi_delete` | Destructive delete with dry-run, confirm token, and protected-path guards |
|
|
150
|
+
|
|
151
|
+
All tools return `{ok: true, ...}` on success or `{ok: false, error: "..."}` on failure. No exceptions are thrown — every handler is wrapped in `safeTool()` to keep MCP transport clean.
|
|
152
|
+
|
|
153
|
+
---
|
|
154
|
+
|
|
155
|
+
## The three keys, in practice
|
|
156
|
+
|
|
157
|
+
Every entity in ACMI lives under three Redis keys following a consistent pattern:
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
acmi:<namespace>:<id>:profile ← JSON object, stable
|
|
161
|
+
acmi:<namespace>:<id>:signals ← JSON object, mutates frequently
|
|
162
|
+
acmi:<namespace>:<id>:timeline ← Redis ZSET (sorted by timestamp ms)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
### Profile — *who/what is this entity*
|
|
166
|
+
|
|
167
|
+
Stable identity. Set once, update rarely.
|
|
168
|
+
|
|
169
|
+
```json
|
|
170
|
+
{
|
|
171
|
+
"name": "Bentley",
|
|
172
|
+
"role": "PM agent",
|
|
173
|
+
"model": "claude-opus-4-7",
|
|
174
|
+
"owner": "mikey"
|
|
175
|
+
}
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Signals — *what is currently true*
|
|
179
|
+
|
|
180
|
+
Frequently-changing state. The LLM's working memory for "what's the situation right now."
|
|
181
|
+
|
|
182
|
+
```json
|
|
183
|
+
{
|
|
184
|
+
"current_focus": "ACMI v1.4 RFC draft",
|
|
185
|
+
"session_state": "active",
|
|
186
|
+
"blocking_items": ["mikey-decision-on-feature-flag"],
|
|
187
|
+
"last_heartbeat_ts": 1778776623639
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Timeline — *everything that happened*
|
|
192
|
+
|
|
193
|
+
Append-only event log. Each event has a timestamp (the ZSET score), source, kind, summary, and correlationId. Following the ACMI Communication Standard v1.1:
|
|
194
|
+
|
|
195
|
+
```json
|
|
196
|
+
{
|
|
197
|
+
"ts": 1778776623639,
|
|
198
|
+
"source": "agent:bentley",
|
|
199
|
+
"kind": "decision",
|
|
200
|
+
"correlationId": "v14RfcDraftStart-1778776623639",
|
|
201
|
+
"parentCorrelationId": "v14LaneAssignment-1778776000000",
|
|
202
|
+
"summary": "[decision @mikey] Drafting v1.4 RFC, starting with workflow identity affinity from gemini-cli's Roundtable v1.2.",
|
|
203
|
+
"tags": ["acmi-protocol", "v14", "rfc"]
|
|
204
|
+
}
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
---
|
|
208
|
+
|
|
209
|
+
## Worked examples
|
|
210
|
+
|
|
211
|
+
### Bootstrap a fresh agent session
|
|
212
|
+
|
|
213
|
+
```javascript
|
|
214
|
+
// As the agent, after MCP host connects:
|
|
215
|
+
const ctx = await mcp.acmi_bootstrap({ agentId: "bentley" });
|
|
216
|
+
// → returns: profile, signals, active threads, last rollup, recent timeline
|
|
217
|
+
```
|
|
218
|
+
|
|
219
|
+
The agent reads one JSON blob and immediately knows: who am I, what was I doing, what threads am I subscribed to, what's open, what did the last session conclude.
|
|
220
|
+
|
|
221
|
+
### Log a multi-agent handoff
|
|
222
|
+
|
|
223
|
+
```javascript
|
|
224
|
+
await mcp.acmi_event({
|
|
225
|
+
namespace: "thread",
|
|
226
|
+
id: "agent-coordination",
|
|
227
|
+
source: "agent:bentley",
|
|
228
|
+
kind: "handoff",
|
|
229
|
+
summary: "[handoff @gemini-cli @mikey] Finished v1.4 RFC draft, handing off to gemini-cli for protocol-side validation.",
|
|
230
|
+
correlationId: "v14RfcHandoff-1778776700000",
|
|
231
|
+
parentCorrelationId: "v14RfcDraftStart-1778776623639"
|
|
232
|
+
});
|
|
233
|
+
```
|
|
234
|
+
|
|
235
|
+
Other agents subscribed to `thread:agent-coordination` see this on their next `acmi_cat` call.
|
|
236
|
+
|
|
237
|
+
### Track a work item end-to-end
|
|
238
|
+
|
|
239
|
+
```javascript
|
|
240
|
+
// Create work item
|
|
241
|
+
await mcp.acmi_work_create({
|
|
242
|
+
id: "deal-acme-corp",
|
|
243
|
+
profile: { title: "ACME Corp — enterprise tier", owner: "duane", value_usd: 47000 }
|
|
244
|
+
});
|
|
245
|
+
|
|
246
|
+
// Progress event
|
|
247
|
+
await mcp.acmi_work_event({
|
|
248
|
+
id: "deal-acme-corp",
|
|
249
|
+
source: "agent:duane",
|
|
250
|
+
summary: "Discovery call complete, technical eval starting Monday."
|
|
251
|
+
});
|
|
252
|
+
|
|
253
|
+
// Update status
|
|
254
|
+
await mcp.acmi_work_signal({
|
|
255
|
+
id: "deal-acme-corp",
|
|
256
|
+
signals: '{"stage":"technical-eval","next_milestone":"poc-demo","blockers":[]}'
|
|
257
|
+
});
|
|
258
|
+
|
|
259
|
+
// Read full context any time
|
|
260
|
+
const deal = await mcp.acmi_work_get({ id: "deal-acme-corp" });
|
|
261
|
+
// → profile + signals + last 50 timeline events + sessions
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
### Multi-stream merge view
|
|
265
|
+
|
|
266
|
+
Read the last 24h of activity across three threads and two agents, time-sorted:
|
|
267
|
+
|
|
268
|
+
```javascript
|
|
269
|
+
const recent = await mcp.acmi_cat({
|
|
270
|
+
keys: [
|
|
271
|
+
"thread:agent-coordination",
|
|
272
|
+
"thread:deal-flow",
|
|
273
|
+
"thread:incident-response",
|
|
274
|
+
"agent:bentley",
|
|
275
|
+
"agent:gemini-cli"
|
|
276
|
+
],
|
|
277
|
+
since: "24h",
|
|
278
|
+
limit: 100
|
|
279
|
+
});
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Set a session rollup for the next agent
|
|
283
|
+
|
|
284
|
+
```javascript
|
|
285
|
+
await mcp.acmi_rollup_set({
|
|
286
|
+
agentId: "bentley",
|
|
287
|
+
rollup: {
|
|
288
|
+
session_window: { start_iso: "2026-05-14T16:30Z", end_iso: "2026-05-14T19:00Z" },
|
|
289
|
+
shipped: ["v1.4 RFC draft", "21 stalled items triaged"],
|
|
290
|
+
next_session_inputs: ["pick up #75 acmi-mcp 1.4.1 publish if Mikey merges"],
|
|
291
|
+
open_blockers: ["mikey-decision-on-rule9-amendment"]
|
|
292
|
+
}
|
|
293
|
+
});
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Next session calls `acmi_bootstrap` and gets this back as `rollup_latest` — instant context.
|
|
297
|
+
|
|
298
|
+
---
|
|
299
|
+
|
|
300
|
+
## Safety features
|
|
301
|
+
|
|
302
|
+
This server has been hardened in production for 6 months. Specific guards:
|
|
303
|
+
|
|
304
|
+
### `validateKeySegments`
|
|
305
|
+
Rejects any segment that's `undefined`, `null`, empty string, the literal string `"undefined"` or `"null"`, contains a colon (`:`), or exceeds 200 chars. Prevents malformed Redis keys from poisoning the store.
|
|
306
|
+
|
|
307
|
+
### `validateJson`
|
|
308
|
+
Catches malformed JSON before SET. Returns a descriptive error including the field name that failed.
|
|
309
|
+
|
|
310
|
+
### `isProtectedKey`
|
|
311
|
+
Refuses mutation of:
|
|
312
|
+
- `acmi:registry:*` (policy registry — fleet-wide config)
|
|
313
|
+
- `acmi:notion-sync:*` (Notion mirror surface — read-only from ACMI side)
|
|
314
|
+
- Empty/null keys (refuse-by-default)
|
|
315
|
+
|
|
316
|
+
### `safeTool`
|
|
317
|
+
Every handler is wrapped in `try/catch`. MCP responses are always shape-stable; failures return `{ok: false, error: "..."}` instead of throwing.
|
|
318
|
+
|
|
319
|
+
### `acmi_delete` two-phase
|
|
320
|
+
- First call must be `dryRun: true` — returns what would be deleted, deletes nothing.
|
|
321
|
+
- Second call requires `confirm: "<exact-key-being-deleted>"` — string mismatch aborts.
|
|
322
|
+
- Protected paths are refused at both phases.
|
|
106
323
|
|
|
107
324
|
---
|
|
108
325
|
|
|
109
|
-
##
|
|
326
|
+
## Environment variables
|
|
110
327
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
328
|
+
| Variable | Required | Purpose |
|
|
329
|
+
|---|---|---|
|
|
330
|
+
| `UPSTASH_REDIS_REST_URL` | yes | Upstash REST endpoint URL |
|
|
331
|
+
| `UPSTASH_REDIS_REST_TOKEN` | yes | Upstash REST auth token |
|
|
332
|
+
| `ACMI_TENANT_ID` | optional | Multi-tenant prefix (default: none) |
|
|
333
|
+
| `ACMI_LOG_LEVEL` | optional | `silent` / `error` / `warn` / `info` / `debug` (default `warn`) |
|
|
116
334
|
|
|
117
335
|
---
|
|
118
336
|
|
|
119
|
-
##
|
|
337
|
+
## Multi-tenant pattern
|
|
120
338
|
|
|
121
|
-
|
|
122
|
-
// 1. Fresh agent session — pull everything you need:
|
|
123
|
-
acmi_bootstrap({ agentId: "claude-engineer" })
|
|
124
|
-
// Returns: profile, signals, active_context, rollup_latest, timeline_recent (last 20), recent_spawns (last 5)
|
|
339
|
+
ACMI is single-tenant by default. To run multiple isolated tenants on one Upstash instance, set `ACMI_TENANT_ID` per host config:
|
|
125
340
|
|
|
126
|
-
|
|
127
|
-
|
|
341
|
+
```json
|
|
342
|
+
{
|
|
343
|
+
"mcpServers": {
|
|
344
|
+
"acmi-prod": {
|
|
345
|
+
"command": "npx",
|
|
346
|
+
"args": ["-y", "@madezmedia/acmi-mcp"],
|
|
347
|
+
"env": {
|
|
348
|
+
"UPSTASH_REDIS_REST_URL": "...",
|
|
349
|
+
"UPSTASH_REDIS_REST_TOKEN": "...",
|
|
350
|
+
"ACMI_TENANT_ID": "madezmedia"
|
|
351
|
+
}
|
|
352
|
+
},
|
|
353
|
+
"acmi-folana": {
|
|
354
|
+
"command": "npx",
|
|
355
|
+
"args": ["-y", "@madezmedia/acmi-mcp"],
|
|
356
|
+
"env": {
|
|
357
|
+
"UPSTASH_REDIS_REST_URL": "...",
|
|
358
|
+
"UPSTASH_REDIS_REST_TOKEN": "...",
|
|
359
|
+
"ACMI_TENANT_ID": "folana"
|
|
360
|
+
}
|
|
361
|
+
}
|
|
362
|
+
}
|
|
363
|
+
}
|
|
128
364
|
```
|
|
129
365
|
|
|
130
|
-
|
|
366
|
+
Keys become `<tenant>:acmi:<namespace>:<id>:<key>` — fully isolated.
|
|
367
|
+
|
|
368
|
+
---
|
|
369
|
+
|
|
370
|
+
## Troubleshooting
|
|
371
|
+
|
|
372
|
+
### "All tools return `ok: false, error: WRONGPASS`"
|
|
373
|
+
Upstash token in your env doesn't match the URL. Double-check the REST URL + token pair come from the same Upstash database.
|
|
374
|
+
|
|
375
|
+
### "Tools/list returns empty"
|
|
376
|
+
Restart the MCP host after editing config. Most hosts only re-read `mcpServers` on launch.
|
|
377
|
+
|
|
378
|
+
### "Bootstrap returns 96KB+, tool errors with `result too large`"
|
|
379
|
+
Your agent has a deep rollup. Tell the agent to read `rollup_latest` separately via `acmi_get` and limit timeline depth, instead of one mega-bootstrap.
|
|
380
|
+
|
|
381
|
+
### "`acmi_delete` refuses my dry-run"
|
|
382
|
+
Check if the key matches a protected path. `acmi:registry:*` and `acmi:notion-sync:*` are refused. If you need to delete protected keys, do it in Upstash console manually.
|
|
383
|
+
|
|
384
|
+
---
|
|
385
|
+
|
|
386
|
+
## Architecture & related projects
|
|
387
|
+
|
|
388
|
+
**This package** (`@madezmedia/acmi-mcp`) is the local stdio MCP server for ACMI. There's a sibling family:
|
|
389
|
+
|
|
390
|
+
| Project | Purpose |
|
|
391
|
+
|---|---|
|
|
392
|
+
| [`@madezmedia/acmi`](https://www.npmjs.com/package/@madezmedia/acmi) | TypeScript SDK with `InMemoryAdapter` + `UpstashAdapter` for embedding ACMI directly in apps |
|
|
393
|
+
| [`@madezmedia/acmi-mcp`](https://www.npmjs.com/package/@madezmedia/acmi-mcp) | **This package** — stdio MCP server for Claude Desktop, Cursor, Cline, Windsurf |
|
|
394
|
+
| [acmi-product](https://acmi-product.vercel.app) | Hosted multi-tenant ACMI on Vercel with OAuth 2.1 + PKCE + DCR for Claude Cloud Agents |
|
|
395
|
+
| [acmi-skill](https://github.com/madezmedia/acmi-skill) | Operator playbook teaching agents to use ACMI correctly across every Claude surface |
|
|
396
|
+
|
|
397
|
+
---
|
|
398
|
+
|
|
399
|
+
## Cross-surface notes
|
|
400
|
+
|
|
401
|
+
| Surface | Best fit |
|
|
402
|
+
|---|---|
|
|
403
|
+
| **Claude Desktop / Code** | This npm package via stdio (most reliable) |
|
|
404
|
+
| **Cursor / Cline / Windsurf** | This npm package via stdio |
|
|
405
|
+
| **Claude Web (claude.ai)** | Smithery-hosted OR `acmi-product.vercel.app/api/mcp` with OAuth |
|
|
406
|
+
| **Claude.ai Cloud Agents** | Smithery-hosted via `?config=<base64>` URL pattern |
|
|
407
|
+
| **Perplexity** | Smithery-hosted (Perplexity supports remote MCP) |
|
|
408
|
+
| **Server-side / scripts** | Use `@madezmedia/acmi` SDK directly, not MCP |
|
|
409
|
+
|
|
410
|
+
---
|
|
411
|
+
|
|
412
|
+
## Versioning
|
|
413
|
+
|
|
414
|
+
Following [semver](https://semver.org/):
|
|
415
|
+
- **Major**: breaking changes to tool signatures or protocol semantics
|
|
416
|
+
- **Minor**: new tools, new optional parameters
|
|
417
|
+
- **Patch**: bug fixes, README/doc, internal hardening with no API change
|
|
418
|
+
|
|
419
|
+
**Current: v1.4.0** — restores source under `mcp/` after 1.3.0 was orphaned from its declared `repository.directory` in 5d27e75. Adds `mcpName` field for MCP registry compliance. Comprehensive README rewrite.
|
|
420
|
+
|
|
421
|
+
See [CHANGELOG](https://github.com/madezmedia/acmi/blob/main/CHANGELOG.md) for history.
|
|
131
422
|
|
|
132
423
|
---
|
|
133
424
|
|
|
134
|
-
##
|
|
425
|
+
## Sponsorship & support
|
|
135
426
|
|
|
136
|
-
|
|
427
|
+
ACMI is an open MIT protocol. We are seeking partners who believe in the future of autonomous agent fleets.
|
|
137
428
|
|
|
138
|
-
- **
|
|
139
|
-
- **
|
|
140
|
-
- **
|
|
429
|
+
- **Infrastructure Partners**: Upstash, Redis, Vercel
|
|
430
|
+
- **Protocol Adopters**: Companies building reliable multi-agent architectures
|
|
431
|
+
- **Issues Agent**: We run an ACMI-native issues agent on this repo with a **48h resolution SLA**. Every GitHub issue is mirrored to our coordination thread; bugs are fixed by our multi-agent fleet (Claude, Gemini, Codex) and verified before close.
|
|
141
432
|
|
|
142
|
-
|
|
143
|
-
- CLI: `npx @madezmedia/acmi <command>`
|
|
144
|
-
- HTTP: roadmap item — REST gateway for non-Redis hosts
|
|
145
|
-
- Direct Redis: REST API (Upstash) — what this MCP wraps
|
|
433
|
+
Read more in [ABOUT.md](https://github.com/madezmedia/acmi/blob/main/ABOUT.md).
|
|
146
434
|
|
|
147
435
|
---
|
|
148
436
|
|
|
149
437
|
## License
|
|
150
438
|
|
|
151
|
-
MIT © Michael Shaw / Mad EZ Media
|
|
439
|
+
MIT © Michael Shaw / Mad EZ Media. See [LICENSE](./LICENSE).
|
|
440
|
+
|
|
441
|
+
---
|
|
442
|
+
|
|
443
|
+
## Links
|
|
444
|
+
|
|
445
|
+
- **Protocol spec**: [github.com/madezmedia/acmi/blob/main/SPEC.md](https://github.com/madezmedia/acmi/blob/main/SPEC.md)
|
|
446
|
+
- **Product page**: [v3-ten-beta.vercel.app/acmi](https://v3-ten-beta.vercel.app/acmi/)
|
|
447
|
+
- **GitHub**: [github.com/madezmedia/acmi](https://github.com/madezmedia/acmi)
|
|
448
|
+
- **Issues / bugs**: [github.com/madezmedia/acmi/issues](https://github.com/madezmedia/acmi/issues)
|
|
449
|
+
- **Smithery listing**: [smithery.ai/@madezmediapartners/acmi-mcp](https://smithery.ai/@madezmediapartners/acmi-mcp)
|
|
450
|
+
- **Manifesto** (Three Keys v1.0): [MANIFESTO.md](https://github.com/madezmedia/acmi/blob/main/MANIFESTO.md)
|
|
451
|
+
|
|
452
|
+
---
|
|
453
|
+
|
|
454
|
+
*Built with intent by Mad EZ Media in Buffalo, NY. Three keys. That's the whole protocol.*
|
package/package.json
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@madezmedia/acmi-mcp",
|
|
3
|
-
"
|
|
4
|
-
"
|
|
3
|
+
"mcpName": "io.github.madezmedia/acmi-mcp",
|
|
4
|
+
"version": "1.4.0",
|
|
5
|
+
"description": "MCP Server for ACMI — Agentic Context Memory Interface. 16 tools for persistent agent memory, timeline events, work items, and multi-agent coordination on Upstash Redis.",
|
|
5
6
|
"type": "module",
|
|
6
7
|
"main": "mcp-server.mjs",
|
|
7
8
|
"bin": {
|
|
8
|
-
"acmi-mcp": "mcp-server.mjs"
|
|
9
|
+
"acmi-mcp": "./mcp-server.mjs"
|
|
9
10
|
},
|
|
10
11
|
"files": [
|
|
11
12
|
"mcp-server.mjs",
|