@kezlahd/atlas-mcp 0.1.0 → 0.2.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 +113 -77
- package/dist/api.js +3 -0
- package/dist/api.js.map +1 -1
- package/dist/index.js +2925 -307
- package/dist/index.js.map +1 -1
- package/dist/section-catalog.js +42 -8
- package/dist/section-catalog.js.map +1 -1
- package/dist/tools/read-achievements.js +32 -0
- package/dist/tools/read-achievements.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,77 +1,113 @@
|
|
|
1
|
-
# @kezlahd/atlas-mcp
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
}
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
"
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
}
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
|
51
|
-
|
|
52
|
-
| `
|
|
53
|
-
| `
|
|
54
|
-
| `
|
|
55
|
-
| `
|
|
56
|
-
| `
|
|
57
|
-
| `
|
|
58
|
-
| `
|
|
59
|
-
| `
|
|
60
|
-
| `
|
|
61
|
-
| `
|
|
62
|
-
| `
|
|
63
|
-
| `
|
|
64
|
-
| `
|
|
65
|
-
| `
|
|
66
|
-
| `
|
|
67
|
-
| `
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
1
|
+
# @kezlahd/atlas-mcp
|
|
2
|
+
|
|
3
|
+
[](https://www.npmjs.com/package/@kezlahd/atlas-mcp)
|
|
4
|
+
[](https://github.com/KezLahd/atlas/blob/master/LICENSE)
|
|
5
|
+
|
|
6
|
+
MCP server that lets Claude Code (and other MCP-aware AI agents) edit Atlas doc templates, files, and gear directly. Sibling of `@kezlahd/atlas-cli` – same auth (Bearer token), same endpoints, same optimistic-concurrency safety (get-then-put with etag).
|
|
7
|
+
|
|
8
|
+
## Setup in Claude Code
|
|
9
|
+
|
|
10
|
+
1. Mint a token: [Atlas](https://atlas.mjsons.net) → workspace → Settings → API keys → Mint token. Copy the plaintext.
|
|
11
|
+
2. Add the server to your Claude Code MCP config (usually `~/.claude/config.json` or `claude_desktop_config.json`):
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"mcpServers": {
|
|
16
|
+
"atlas": {
|
|
17
|
+
"command": "npx",
|
|
18
|
+
"args": ["-y", "@kezlahd/atlas-mcp"],
|
|
19
|
+
"env": {
|
|
20
|
+
"ATLAS_TOKEN": "atlas_pat_…",
|
|
21
|
+
"ATLAS_WORKSPACE": "acme-inc"
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
3. Restart Claude Code. You should see the `atlas` server connect on stderr.
|
|
29
|
+
|
|
30
|
+
For dev – run out of the workspace instead:
|
|
31
|
+
|
|
32
|
+
```json
|
|
33
|
+
{
|
|
34
|
+
"mcpServers": {
|
|
35
|
+
"atlas": {
|
|
36
|
+
"command": "pnpm",
|
|
37
|
+
"args": ["--filter", "@kezlahd/atlas-mcp", "dev"],
|
|
38
|
+
"cwd": "/path/to/the-studio",
|
|
39
|
+
"env": {
|
|
40
|
+
"ATLAS_TOKEN": "atlas_pat_…",
|
|
41
|
+
"ATLAS_WORKSPACE": "acme-inc"
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Tools exposed
|
|
49
|
+
|
|
50
|
+
| Tool | Purpose | Scope |
|
|
51
|
+
|---|---|---|
|
|
52
|
+
| `atlas_list_docs` | List docs in the workspace (pass `deleted: true` for the trash bucket) | `templates:list` |
|
|
53
|
+
| `atlas_get_template` | Fetch full template content (returns etag) | `templates:get` |
|
|
54
|
+
| `atlas_list_sections` | Summarise section ids + types + titles (cheap) | `templates:get` |
|
|
55
|
+
| `atlas_describe_section_type` | Look up what fields a section type takes | none |
|
|
56
|
+
| `atlas_update_section` | Edit one section by id – safe, scoped, auto-etag | `templates:update` |
|
|
57
|
+
| `atlas_update_template` | Replace the whole template – for restructuring | `templates:update` |
|
|
58
|
+
| `atlas_list_revisions` | List revision history for a template | `templates:list-revisions` |
|
|
59
|
+
| `atlas_restore_revision` | Restore a template to an earlier revision | `templates:restore-revision` |
|
|
60
|
+
| `atlas_doc_create` | Create a new doc from scratch | `templates:create` |
|
|
61
|
+
| `atlas_doc_delete` | Soft-delete a doc (30-day trash); pass `purge: true` for forever | `templates:delete` |
|
|
62
|
+
| `atlas_restore_doc` | Restore a soft-deleted doc from the Recently deleted bucket | `templates:update` |
|
|
63
|
+
| `atlas_purge_doc` | Hard-delete a soft-deleted doc (requires it's already in the trash) | `templates:delete` |
|
|
64
|
+
| `atlas_list_files` | List workspace files with signed URLs | `files:list` |
|
|
65
|
+
| `atlas_get_file_url` | Fetch a signed URL for a single file | `files:list` |
|
|
66
|
+
| `atlas_upload_file` | Upload a local file to workspace storage | `files:upload` |
|
|
67
|
+
| `atlas_rename_file` | Rename a workspace file | `files:rename` |
|
|
68
|
+
| `atlas_set_file_alt` | Update the alt-text metadata for a file | `files:edit-alt` |
|
|
69
|
+
| `atlas_delete_file` | Delete a workspace file | `files:delete` |
|
|
70
|
+
| `atlas_list_gear` | List gear items in the workspace (pass `deleted: true` for the trash bucket) | `gear:list` |
|
|
71
|
+
| `atlas_add_gear` | Add a new gear item | `gear:add` |
|
|
72
|
+
| `atlas_update_gear` | Patch an existing gear item | `gear:update` |
|
|
73
|
+
| `atlas_delete_gear` | Soft-delete a gear item (30-day trash); pass `purge: true` for forever | `gear:delete` |
|
|
74
|
+
| `atlas_restore_gear` | Restore a soft-deleted gear item | `gear:update` |
|
|
75
|
+
| `atlas_purge_gear` | Hard-delete a soft-deleted gear item | `gear:delete` |
|
|
76
|
+
| `atlas_import_gear` | Bulk import gear from CSV | `gear:import` |
|
|
77
|
+
| `atlas_list_shots` | List shot items (pass `deleted: true` for the trash bucket) | `shots:list` |
|
|
78
|
+
| `atlas_add_shot` | Add a new shot item | `shots:add` |
|
|
79
|
+
| `atlas_update_shot` | Patch an existing shot item (empty string clears image/notes) | `shots:update` |
|
|
80
|
+
| `atlas_delete_shot` | Soft-delete a shot item (30-day trash); pass `purge: true` for forever | `shots:delete` |
|
|
81
|
+
| `atlas_restore_shot` | Restore a soft-deleted shot item | `shots:update` |
|
|
82
|
+
| `atlas_purge_shot` | Hard-delete a soft-deleted shot item | `shots:delete` |
|
|
83
|
+
| `atlas_import_shots` | Bulk import shots (name/kind/notes only – wire gear per-row after) | `shots:import` |
|
|
84
|
+
| `atlas_list_events` | List calendar events (date/status/colour filters, cursor pagination) | `events:list` |
|
|
85
|
+
| `atlas_get_event` | Read one event + its crew assignments | `events:get` |
|
|
86
|
+
| `atlas_create_event` | Schedule a new calendar event (title + starts_at required; 30-min minimum for timed events) | `events:create` |
|
|
87
|
+
| `atlas_update_event` | Patch an existing event — only fields you send are written | `events:update` |
|
|
88
|
+
| `atlas_delete_event` | **Permanent** hard delete (no trash for events — always confirm with the user) | `events:delete` |
|
|
89
|
+
| `atlas_assign_event` | Add crew to an event (idempotent — repeat returns existing assignment) | `events:assign` |
|
|
90
|
+
| `atlas_unassign_event` | Remove a crew assignment from an event | `events:assign` |
|
|
91
|
+
| `atlas_get_workspace` | Read the workspace's name, slug, logo, brand theme (1h signed logo URL) | `workspace:read` |
|
|
92
|
+
| `atlas_update_workspace` | Patch name / slug / logo_bg / brand theme (partial – only sent fields change) | `workspace:write` |
|
|
93
|
+
| `atlas_upload_workspace_logo` | Multipart upload of a local PNG/JPG/WebP as the workspace logo | `workspace:write` |
|
|
94
|
+
|
|
95
|
+
Every template write is journaled to `doc_template_revisions` server-side, so any bad push from a chat can be reverted from the UI.
|
|
96
|
+
|
|
97
|
+
## The pattern to teach Claude
|
|
98
|
+
|
|
99
|
+
> Pull `atlas_list_sections` first (cheap), then `atlas_describe_section_type` for the section you're editing, then `atlas_update_section` with the correct shape. Only reach for `atlas_update_template` when you're restructuring the doc.
|
|
100
|
+
|
|
101
|
+
## Last verified against prod
|
|
102
|
+
|
|
103
|
+
The underlying `/api/v1/*` endpoints all round-tripped from the CLI on `2026-09-28` against `https://atlas.mjsons.net` — see the CLI README for the per-command matrix. MCP tools share the same routes + auth path, so the same guarantees apply. If you're wiring a fresh Claude Desktop config, expect every tool in the table above to be reachable with a token minted from Settings → API keys with the matching scope group ticked.
|
|
104
|
+
|
|
105
|
+
## Related packages
|
|
106
|
+
|
|
107
|
+
- [`@kezlahd/atlas-cli`](https://www.npmjs.com/package/@kezlahd/atlas-cli) – terminal client that hits the same endpoints, for humans instead of agents.
|
|
108
|
+
|
|
109
|
+
Source for both packages lives in the [Atlas monorepo](https://github.com/KezLahd/atlas).
|
|
110
|
+
|
|
111
|
+
## License
|
|
112
|
+
|
|
113
|
+
MIT
|
package/dist/api.js
CHANGED
|
@@ -37,6 +37,9 @@ export async function apiRequest(cfg, path, opts = {}) {
|
|
|
37
37
|
const headers = {
|
|
38
38
|
Authorization: `Bearer ${cfg.token}`,
|
|
39
39
|
Accept: "application/json",
|
|
40
|
+
// Server keys revision `source` off this — MCP writes should surface
|
|
41
|
+
// as "via Claude / MCP" in the history drawer, not "via api".
|
|
42
|
+
"User-Agent": "atlas-mcp/0.1.0",
|
|
40
43
|
};
|
|
41
44
|
if (opts.body !== undefined)
|
|
42
45
|
headers["Content-Type"] = "application/json";
|
package/dist/api.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,eAAe,GAAG,0BAA0B,CAAC;AAQnD,MAAM,UAAU,aAAa;IAC3B,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC;IACtC,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC;IAC9C,MAAM,MAAM,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,eAAe,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IACjF,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,MAAM,IAAI,KAAK,CACb,8GAA8G,CAC/G,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,IAAI,KAAK,CACb,kFAAkF,CACnF,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACtC,CAAC;AAED,MAAM,OAAO,QAAS,SAAQ,KAAK;IACjC,MAAM,CAAS;IACf,IAAI,CAAU;IACd,YAAY,MAAc,EAAE,IAAa,EAAE,OAAe;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;IACzB,CAAC;CACF;AASD,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,GAAmB,EACnB,IAAY,EACZ,OAAoB,EAAE;IAEtB,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QACf,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAChD,IAAI,CAAC,KAAK,SAAS;gBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;QAC1D,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAA2B;QACtC,aAAa,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE;QACpC,MAAM,EAAE,kBAAkB;
|
|
1
|
+
{"version":3,"file":"api.js","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}
|