@naumu/mcp 0.11.0 → 0.12.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.
Files changed (4) hide show
  1. package/README.md +176 -34
  2. package/dist/index.js +546 -128
  3. package/package.json +8 -7
  4. package/server.json +58 -0
package/README.md CHANGED
@@ -1,14 +1,59 @@
1
1
  # @naumu/mcp
2
2
 
3
- MCP server for [Naumu](https://naumu.ai) — access your knowledge graph from Claude Code, Cursor, and other AI coding agents.
3
+ MCP server for [Naumu](https://naumu.ai) - access your knowledge graph from Claude Code, Cursor, and other AI agents.
4
4
 
5
- ## Setup
5
+ Naumu speaks MCP over two transports:
6
+
7
+ 1. **Remote, over OAuth** at `https://naumu.ai/api/mcp` - the recommended path. You sign in through your browser, and there is no API key to create, paste, or keep in sync. This package is not involved.
8
+ 2. **Local stdio**, this package, launched on demand with `npx` and authenticated with an API key. Use it for clients that cannot do browser OAuth: CI jobs, bot and external-agent identities, and older stdio-only harnesses.
9
+
10
+ ## Recommended setup: remote MCP over OAuth
11
+
12
+ Register the server once. The first time a session uses a Naumu tool, your browser opens to sign in and approve access. After that the tools are available in every session.
13
+
14
+ ### Claude Code
15
+
16
+ ```bash
17
+ claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp
18
+ ```
19
+
20
+ `--scope user` registers the server for your whole machine rather than the current project, so you do not have to repeat it per repository.
21
+
22
+ ### Cursor
23
+
24
+ ```json
25
+ {
26
+ "mcpServers": {
27
+ "naumu": {
28
+ "url": "https://naumu.ai/api/mcp"
29
+ }
30
+ }
31
+ }
32
+ ```
33
+
34
+ Leave any OAuth client ID and secret fields blank. Naumu registers the client for you automatically during sign-in, using Dynamic Client Registration (DCR).
35
+
36
+ Other MCP-capable clients that support remote servers follow the same shape: point them at `https://naumu.ai/api/mcp` and let the browser handle sign-in. Use the front-end origin (`naumu.ai`), not a backend address - sign-in and consent rely on your Naumu session, which lives on the front-end origin.
37
+
38
+ You can revoke a connected tool's access at any time in Naumu under **Settings > Your agents**, in the **Active access** list.
39
+
40
+ See [Local MCP](https://naumu.ai/docs/local-mcp) for the full walkthrough.
41
+
42
+ ## Fallback setup: local stdio server with an API key
43
+
44
+ Use this package when your client cannot do browser OAuth - CI, bots and external agent identities, or a harness that only speaks stdio.
6
45
 
7
46
  ### 1. Get an API key
8
47
 
9
- Generate an API key from your Naumu account settings.
48
+ 1. Open **Settings > Your agents** in Naumu.
49
+ 2. Select **Create an API key** and give it a recognizable name (such as the tool it is for).
50
+ 3. Copy the key right away. It is shown only once and cannot be retrieved later. Keys start with `nmu_`.
51
+
52
+ Use a separate key per tool, so a leak only costs you that one key.
10
53
 
11
- ### 2. Configure your IDE
54
+ ### 2. Configure your client
55
+
56
+ You do not install this package globally; your client launches it on demand with `npx`.
12
57
 
13
58
  #### Claude Code
14
59
 
@@ -20,8 +65,6 @@ claude mcp add naumu -s user \
20
65
 
21
66
  #### Cursor
22
67
 
23
- Add to your Cursor MCP settings:
24
-
25
68
  ```json
26
69
  {
27
70
  "mcpServers": {
@@ -36,39 +79,138 @@ Add to your Cursor MCP settings:
36
79
  }
37
80
  ```
38
81
 
82
+ ### Environment variables
83
+
84
+ | Variable | Required | Default | Description |
85
+ |----------|----------|---------|-------------|
86
+ | `NAUMU_API_KEY` | Yes | - | Your API key (starts with `nmu_`) |
87
+ | `NAUMU_API_URL` | No | `https://naumu.ai` | Naumu API base URL. You do not need to set this |
88
+
39
89
  ## Available tools
40
90
 
91
+ Both transports expose the same tool surface. Tools marked **bot** are only registered for bot identity keys (`nmu_bot_*`), which additionally receive a filtered subset based on the identity's permissions.
92
+
93
+ ### Spaces and members
94
+
41
95
  | Tool | Description |
42
96
  |------|-------------|
43
- | `naumu_list_graphs` | List all knowledge graphs you have access to |
44
- | `naumu_get_schema` | Get the schema (node types, relationships) for a graph |
45
- | `naumu_text_search` | Search nodes by exact text match on labels and content |
46
- | `naumu_semantic_search` | Search nodes by meaning using AI embeddings |
47
- | `naumu_filter` | Filter nodes by type and attributes with deterministic results |
48
- | `naumu_get_node` | Get a node with all its properties and connections |
49
- | `naumu_add_node` | Create a new node |
50
- | `naumu_update_node` | Update an existing node |
51
- | `naumu_add_edge` | Create a relationship between two nodes |
52
- | `naumu_remove_node` | Delete a node and its connections |
53
- | `naumu_remove_edge` | Delete a relationship |
54
- | `naumu_create_topic` | Create a topic (filing destination) in a space; admin-only, name must be a lowercase slug, returns an `id` for `topicIds` params |
55
- | `naumu_ask` | Ask @Naumu a question and get a synthesised answer back (answer + sources + confidence + threadId + status); leaves a visible thread in the space |
56
- | `naumu_delegate` | Hand @Naumu a task to carry out asynchronously (add knowledge, make changes); returns a `threadId` immediately, then poll with `naumu_read_thread` |
57
- | `naumu_read_thread` | Read a thread's messages; each message carries a `status` of `processing` or `complete` |
58
- | `naumu_whoami` | (Bot keys) Self-introspection — id, graphId, name, instructions, allowed tools |
59
- | `naumu_list_threads` | (Bot keys) List threads in your graph with `isParticipant` flag |
60
- | `naumu_get_thread` | (Bot keys) Fetch a thread plus its human + bot participant rosters |
61
- | `naumu_create_thread` | (Bot keys only) Start a new conversation, attach participants, post initial message, optionally file into topics via `topicIds` |
62
- | `naumu_request_attachment_upload` | (Bot keys) Get a presigned S3 URL to upload a file; pair with `naumu_post_message`'s `attachmentIds` |
63
- | `naumu_add_reaction` | (Bot keys) Add an emoji reaction to a message in a thread you participate in (idempotent) |
64
- | `naumu_remove_reaction` | (Bot keys) Remove your own reaction from a message |
65
-
66
- ## Environment variables
97
+ | `naumu_list_graphs` | List every space (graph) the key can access, with ids, names, and roles |
98
+ | `naumu_create_graph` | Create a new, empty space owned by the authenticated user |
99
+ | `naumu_list_members` | List a space's members with their roles |
100
+ | `naumu_whoami` | Return who the calling key is (user, or bot identity with its graph and allowed tools) |
67
101
 
68
- | Variable | Required | Default | Description |
69
- |----------|----------|---------|-------------|
70
- | `NAUMU_API_KEY` | Yes | — | Your API key (starts with `nmu_`) |
71
- | `NAUMU_API_URL` | No | `https://naumu.ai` | Naumu API base URL (only change for self-hosted) |
102
+ ### Schema
103
+
104
+ | Tool | Description |
105
+ |------|-------------|
106
+ | `naumu_get_schema` | Get a space's schema (node types, attributes, connections) |
107
+ | `naumu_update_schema` | Replace the schema with a full new definition |
108
+ | `naumu_add_node_type` | Add one node type without resending the whole schema |
109
+ | `naumu_add_connection` | Add one connection from an existing node type to another |
110
+ | `naumu_add_attribute` | Add or extend an attribute on an existing node type |
111
+ | `naumu_list_schema_violations` | Audit a space against its schema and report violations |
112
+
113
+ ### Reading the graph
114
+
115
+ | Tool | Description |
116
+ |------|-------------|
117
+ | `naumu_search` | Hybrid (meaning plus text) search over graph nodes |
118
+ | `naumu_filter` | Filter nodes by type and attributes, with deterministic and complete results |
119
+ | `naumu_get_node` | Get one node with its properties, edges, notes, threads, and generated context |
120
+ | `naumu_list_node_connections` | List a single node's connections |
121
+ | `naumu_list_dense_nodes` | Find over-connected hub nodes by child count |
122
+ | `naumu_ask` | Ask @Naumu a question and get a synthesised, node-grounded answer with sources and confidence |
123
+
124
+ ### Writing to the graph
125
+
126
+ | Tool | Description |
127
+ |------|-------------|
128
+ | `naumu_add_node` | Create 1-25 nodes in one call |
129
+ | `naumu_update_node` | Overwrite properties of an existing node |
130
+ | `naumu_remove_node` | Delete a node and all of its connections (destructive) |
131
+ | `naumu_add_edge` | Create 1-25 edges between existing nodes |
132
+ | `naumu_remove_edge` | Delete one edge identified by (source, target, label) |
133
+ | `naumu_remove_edges_bulk` | Delete 1-100 edges in one atomic call |
134
+ | `naumu_reparent` | Atomically swap a node's parent edge |
135
+ | `naumu_batch_reparent` | Reparent 1-25 nodes onto a shared new parent |
136
+ | `naumu_delegate` | Hand @Naumu a task to carry out asynchronously; returns a `threadId` to poll |
137
+
138
+ ### Threads and topics
139
+
140
+ | Tool | Description |
141
+ |------|-------------|
142
+ | `naumu_list_threads` | List threads by last activity, with an `isParticipant` flag |
143
+ | `naumu_get_thread` | Fetch one thread plus its human and bot participant rosters |
144
+ | `naumu_read_thread` | Read a thread's messages; each carries `processing` or `complete` status |
145
+ | `naumu_post_message` | Post a markdown message in a thread you participate in |
146
+ | `naumu_create_thread` | **bot** Start a new conversation, attach participants, post a first message, optionally file into topics |
147
+ | `naumu_add_reaction` | Add an emoji reaction to a message (idempotent) |
148
+ | `naumu_remove_reaction` | Remove your own reaction from a message |
149
+ | `naumu_typing` | Show or hide your "is typing" indicator in a thread |
150
+ | `naumu_list_topics` | List a space's topics (filing destinations) for use in `topicIds` |
151
+ | `naumu_create_topic` | Create a topic; admin-only, name must be a lowercase slug |
152
+
153
+ ### Notes
154
+
155
+ | Tool | Description |
156
+ |------|-------------|
157
+ | `naumu_create_note` | Create a note, optionally with its full markdown body in the same call |
158
+ | `naumu_note_read` | Read a note's current markdown plus the nodes it is tied to |
159
+ | `naumu_note_append` | Append markdown blocks to the end of a note |
160
+ | `naumu_note_insert` | Insert markdown immediately after a named heading |
161
+ | `naumu_note_replace_section` | Replace the body under a named heading |
162
+ | `naumu_note_delete_section` | Delete a heading and its body (destructive) |
163
+ | `naumu_note_replace` | Replace an entire note's content (destructive) |
164
+ | `naumu_note_find_replace` | Literal find and replace within a note |
165
+
166
+ ### Attachments
167
+
168
+ | Tool | Description |
169
+ |------|-------------|
170
+ | `naumu_request_attachment_upload` | Get a presigned S3 URL to upload a file, then reference it via `attachmentIds` |
171
+ | `naumu_get_attachment` | Read a chat attachment by `attachmentId` |
172
+ | `naumu_persist_canvas_attachment` | Promote a canvas-bound pending attachment to a persisted one |
173
+
174
+ ### Space admission
175
+
176
+ | Tool | Description |
177
+ |------|-------------|
178
+ | `naumu_admission_status` | Show who can auto-join a space and who is waiting for approval |
179
+ | `naumu_whitelist_members` | Whitelist emails so those people auto-join on sign-in |
180
+ | `naumu_resolve_admission` | Join (or request to join) the space a repo's `.naumu` file references |
181
+ | `naumu_resolve_join_request` | Approve or deny a pending join request |
182
+
183
+ ### ChatGPT compatibility
184
+
185
+ The OpenAI MCP surface requires tools literally named `search` and `fetch`. These wrap cross-space search and node reads in the response shapes that client expects.
186
+
187
+ | Tool | Description |
188
+ |------|-------------|
189
+ | `search` | Search across every accessible space; returns `{ results: [{ id, title, url }] }` |
190
+ | `fetch` | Fetch a node returned by `search`; returns `{ id, title, text, url }` |
191
+
192
+ ## Troubleshooting
193
+
194
+ When the stdio server is misconfigured it exits before the MCP handshake, and most clients simply show no server at all, with no error. Run the built-in self-check to find out why:
195
+
196
+ ```bash
197
+ npx -y -p @naumu/mcp naumu-mcp doctor
198
+ ```
199
+
200
+ It checks, in order, that `NAUMU_API_KEY` is set (the key itself is never printed), that the API is reachable and accepts the key, and that this build matches the latest published version. It prints one line per check plus a verdict, and exits non-zero if anything failed:
201
+
202
+ ```
203
+ naumu-mcp doctor (v0.11.1, API https://naumu.ai)
204
+
205
+ [fail] API key: NAUMU_API_KEY is missing from the environment
206
+ [warn] API: reachable (https://naumu.ai answered HTTP 403), but there is no NAUMU_API_KEY to verify
207
+ [ok] Version: running 0.11.1 (npm latest)
208
+
209
+ Verdict: 1 check failed - the MCP server will not work until this is fixed.
210
+ Most likely fix: Set NAUMU_API_KEY - create a key at https://naumu.ai/settings (Settings > Your agents > Create an API key)
211
+ ```
212
+
213
+ Run it with the same environment your MCP client uses, otherwise the key check reports on your shell rather than on the client's configuration.
72
214
 
73
215
  ## License
74
216