@heuresis/mcp 1.0.0-rc.5 → 1.0.0-rc.7
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 +148 -152
- package/dist/cli.js +6 -7
- package/dist/cloudTools.js +5 -15
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,152 +1,148 @@
|
|
|
1
|
-
# @heuresis/mcp
|
|
2
|
-
|
|
3
|
-
A Model Context Protocol (MCP) server that
|
|
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
|
-
The
|
|
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
|
-
npx @heuresis/mcp
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
MCP
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
|
|
143
|
-
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
## License
|
|
151
|
-
|
|
152
|
-
AGPL-3.0-or-later.
|
|
1
|
+
# @heuresis/mcp
|
|
2
|
+
|
|
3
|
+
A Model Context Protocol (MCP) server that exposes a Heuresis workspace
|
|
4
|
+
to any MCP-capable client (Claude Desktop, Claude Code, Cursor,
|
|
5
|
+
Windsurf, custom agents). The server logs into the user's Heuresis
|
|
6
|
+
account, talks to the same Supabase project the webapp talks to, and
|
|
7
|
+
respects the same RLS. Webapp and MCP are two front-ends to one cloud
|
|
8
|
+
workspace.
|
|
9
|
+
|
|
10
|
+
Current version: `1.0.0-rc.7`.
|
|
11
|
+
|
|
12
|
+
## Install
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install -g @heuresis/mcp
|
|
16
|
+
# or on demand without installing:
|
|
17
|
+
npx -y @heuresis/mcp
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
## Quickstart
|
|
21
|
+
|
|
22
|
+
### 1. Link this machine to your Heuresis account
|
|
23
|
+
|
|
24
|
+
```bash
|
|
25
|
+
npx -y @heuresis/mcp login
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
The CLI prints a device code and a one-click URL of the form
|
|
29
|
+
`https://heuresis.app/device?code=XXXX-XXXX`. Open it in your browser,
|
|
30
|
+
sign in if you aren't already, and confirm the device. The CLI polls
|
|
31
|
+
in the background and writes credentials to
|
|
32
|
+
`~/.heuresis/credentials.json` (chmod 600 on POSIX) the moment you
|
|
33
|
+
confirm. Subsequent runs of the MCP are silent.
|
|
34
|
+
|
|
35
|
+
The login flow rides three Supabase Edge Functions:
|
|
36
|
+
`mcp-device-start`, `mcp-device-grant`, and `mcp-device-poll`.
|
|
37
|
+
|
|
38
|
+
To unlink a machine: `npx @heuresis/mcp logout`, or open
|
|
39
|
+
Settings ▸ Connected devices in the webapp to revoke remotely.
|
|
40
|
+
|
|
41
|
+
`npx @heuresis/mcp whoami` confirms which account a machine is
|
|
42
|
+
currently linked to.
|
|
43
|
+
|
|
44
|
+
### 2. Point your MCP client at it
|
|
45
|
+
|
|
46
|
+
**Claude Desktop.** Edit
|
|
47
|
+
`~/Library/Application Support/Claude/claude_desktop_config.json` on
|
|
48
|
+
macOS, or `%APPDATA%/Claude/claude_desktop_config.json` on Windows:
|
|
49
|
+
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Claude Code / Cursor / Windsurf.** Drop a `.mcp.json` in the
|
|
59
|
+
workspace root:
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"mcpServers": {
|
|
64
|
+
"heuresis": { "command": "npx", "args": ["-y", "@heuresis/mcp"] }
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
Restart the client. The Heuresis tools appear in the tool menu.
|
|
70
|
+
|
|
71
|
+
### 3. CLI subcommands
|
|
72
|
+
|
|
73
|
+
```bash
|
|
74
|
+
npx @heuresis/mcp whoami # show the linked account + device
|
|
75
|
+
npx @heuresis/mcp logout # delete the credentials file
|
|
76
|
+
npx @heuresis/mcp --help # all options
|
|
77
|
+
npx @heuresis/mcp --no-realtime # boot once with live sync turned off (persisted)
|
|
78
|
+
npx @heuresis/mcp --realtime # re-enable live sync
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Live sync
|
|
82
|
+
|
|
83
|
+
When the MCP boots in cloud mode it subscribes to the workspace over
|
|
84
|
+
Supabase Realtime and notifies the client whenever a `nodes`, `edges`,
|
|
85
|
+
`projects`, or `ideas` row changes. Edits made in the webapp show up
|
|
86
|
+
in the agent's view without a manual refresh, and writes from one
|
|
87
|
+
MCP-connected client reach any other connected client the same way.
|
|
88
|
+
Pass `--no-realtime` to disable the subscription (useful if the
|
|
89
|
+
chatter is noisy or the client logs every notification). The
|
|
90
|
+
preference is saved to `~/.heuresis/config.json` so the flag only
|
|
91
|
+
needs to be passed once.
|
|
92
|
+
|
|
93
|
+
## Tools
|
|
94
|
+
|
|
95
|
+
34 tools total: 31 data tools against the cloud workspace, plus 3
|
|
96
|
+
operator tools that drive the same ideation operators the webapp uses.
|
|
97
|
+
|
|
98
|
+
**Reads (10).** `get_workspace_summary`, `list_projects`,
|
|
99
|
+
`get_project_graph`, `list_concepts`, `list_edges`, `get_subtree`,
|
|
100
|
+
`get_concept`, `search_concepts`, `find_concepts`,
|
|
101
|
+
`list_recent_decisions`. Most agent sessions start with
|
|
102
|
+
`get_workspace_summary` or `list_projects`.
|
|
103
|
+
|
|
104
|
+
**Writes (21).** Concepts: `add_concept`, `update_concept`,
|
|
105
|
+
`bulk_add_concepts`, `set_parent`, `validate_concept`, `set_standing`,
|
|
106
|
+
`archive_concept`, `unarchive_concept`, `star_concept`,
|
|
107
|
+
`remove_concept`. Edges: `link_concepts`, `add_kref`. Ideas:
|
|
108
|
+
`create_idea`, `rename_idea`, `recolor_idea`, `set_idea_members`,
|
|
109
|
+
`add_to_idea`, `delete_idea`. Projects: `create_project`,
|
|
110
|
+
`update_project`, `delete_project`. Every write stamps a row in
|
|
111
|
+
`public.provenance` with `origin='mcp'` so the webapp's session log
|
|
112
|
+
shows which surface made the change.
|
|
113
|
+
|
|
114
|
+
**Operator runs (3).** `run_operator` (generate candidates with
|
|
115
|
+
Branch / Matrix / ASIT / TRIZ / Combine / Free / Contradiction),
|
|
116
|
+
`run_operator_and_commit` (same, plus commit the result in one
|
|
117
|
+
round-trip), and `expand_concept` (recursive Branch, capped at depth ×
|
|
118
|
+
breadth ≤ 60).
|
|
119
|
+
|
|
120
|
+
Tool input shapes mirror their counterparts in the webapp's
|
|
121
|
+
`src/agent/tools.ts`, so an agent that uses both surfaces sees a
|
|
122
|
+
uniform contract.
|
|
123
|
+
|
|
124
|
+
Wave-shipping: `find_in_files` (in-browser embedding search) is in the
|
|
125
|
+
webapp but not yet on the MCP.
|
|
126
|
+
|
|
127
|
+
## Legacy snapshot mode (deprecated)
|
|
128
|
+
|
|
129
|
+
The original read-only snapshot reader still works as a fallback while
|
|
130
|
+
users migrate to cloud auth. With no `~/.heuresis/credentials.json`
|
|
131
|
+
and the `HEURESIS_SNAPSHOT` env var set, the server reads a JSON
|
|
132
|
+
export from disk and exposes the original read-only tool set
|
|
133
|
+
(`get_workspace_summary`, `list_projects`, `search_concepts`,
|
|
134
|
+
`get_concept`, `get_subtree`, `get_project_graph`,
|
|
135
|
+
`list_recent_decisions`).
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
export HEURESIS_SNAPSHOT="/absolute/path/to/your-export.json"
|
|
139
|
+
npx @heuresis/mcp
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
This path is deprecated and will be removed in a later release. It is
|
|
143
|
+
here so existing setups keep working through the migration to cloud
|
|
144
|
+
auth.
|
|
145
|
+
|
|
146
|
+
## License
|
|
147
|
+
|
|
148
|
+
AGPL-3.0-or-later.
|
package/dist/cli.js
CHANGED
|
@@ -174,16 +174,15 @@ export async function loginCommand(argv = []) {
|
|
|
174
174
|
log('Pairing init returned no code. Aborting.');
|
|
175
175
|
process.exit(1);
|
|
176
176
|
}
|
|
177
|
-
// 2. Tell the user where to go.
|
|
177
|
+
// 2. Tell the user where to go. The URL has the code baked in as a query
|
|
178
|
+
// param so the device page can pre-fill it; the user just clicks Confirm.
|
|
179
|
+
const confirmUrl = `${deviceBaseUrl}/device?code=${encodeURIComponent(init.code)}`;
|
|
178
180
|
log('');
|
|
179
|
-
log(`
|
|
180
|
-
log(` ${deviceBaseUrl}/device`);
|
|
181
|
+
log(`Open this URL to link this machine to your Heuresis account:`);
|
|
181
182
|
log('');
|
|
182
|
-
log(`
|
|
183
|
-
log(` ${init.code}`);
|
|
183
|
+
log(` ${confirmUrl}`);
|
|
184
184
|
log('');
|
|
185
|
-
log(`
|
|
186
|
-
log(` expires in 15 minutes.`);
|
|
185
|
+
log(`(Code: ${init.code}, in case the page needs it manually. Expires in 15 min.)`);
|
|
187
186
|
log('');
|
|
188
187
|
log(`Waiting for confirmation…`);
|
|
189
188
|
// 3. Poll until ok / 410 / timeout.
|
package/dist/cloudTools.js
CHANGED
|
@@ -853,17 +853,14 @@ export async function listEdges(client, args) {
|
|
|
853
853
|
// ---------------------------------------------------------------------------
|
|
854
854
|
// find_concepts
|
|
855
855
|
// ---------------------------------------------------------------------------
|
|
856
|
-
// Mirrors the webapp `find_concepts` tool
|
|
857
|
-
// by='meaning'
|
|
858
|
-
//
|
|
859
|
-
// back to the same substring search as by='label' and the response carries a
|
|
860
|
-
// `note` explaining the degradation. Phase 19.5 swaps in pgvector when the
|
|
861
|
-
// schema picks it up.
|
|
856
|
+
// Mirrors the webapp `find_concepts` tool, label/substring path only. The
|
|
857
|
+
// webapp's by='meaning' variant relies on in-browser embeddings; that path is
|
|
858
|
+
// not wired on the MCP side, so this tool accepts by='label' only.
|
|
862
859
|
export const findConceptsInput = z
|
|
863
860
|
.object({
|
|
864
861
|
query: z.string().min(1),
|
|
865
862
|
k: z.number().int().positive().max(20).default(10),
|
|
866
|
-
by: z.enum(['
|
|
863
|
+
by: z.enum(['label']).default('label'),
|
|
867
864
|
projectId: z.string().optional(),
|
|
868
865
|
})
|
|
869
866
|
.strict();
|
|
@@ -885,13 +882,6 @@ export async function findConcepts(client, args) {
|
|
|
885
882
|
status: r.status,
|
|
886
883
|
score: 1,
|
|
887
884
|
}));
|
|
888
|
-
if (args.by === 'meaning') {
|
|
889
|
-
return {
|
|
890
|
-
hits,
|
|
891
|
-
mode: 'label',
|
|
892
|
-
note: 'Semantic search not yet wired in MCP (no in-browser embedding model); fell back to label/substring match.',
|
|
893
|
-
};
|
|
894
|
-
}
|
|
895
885
|
return { hits, mode: 'label' };
|
|
896
886
|
}
|
|
897
887
|
// ===========================================================================
|
|
@@ -1591,7 +1581,7 @@ export const CLOUD_TOOLS = [
|
|
|
1591
1581
|
},
|
|
1592
1582
|
{
|
|
1593
1583
|
name: 'find_concepts',
|
|
1594
|
-
description:
|
|
1584
|
+
description: 'Find concepts by label/substring match. Returns up to k hits, each with id, label, status.',
|
|
1595
1585
|
inputSchema: findConceptsInput,
|
|
1596
1586
|
handler: async (client, args) => findConcepts(client, findConceptsInput.parse(args)),
|
|
1597
1587
|
},
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@heuresis/mcp",
|
|
3
|
-
"version": "1.0.0-rc.
|
|
3
|
+
"version": "1.0.0-rc.7",
|
|
4
4
|
"description": "Cloud-authenticated Model Context Protocol server for a Heuresis workspace. Logs into the user's Heuresis account and lets any MCP client (Claude Desktop, Claude Code, Cursor, custom agents) read and write the same workspace the webapp uses. 31 data tools, 3 operator tools (Branch/Matrix/C-K/ASIT/TRIZ/Free/Combine/Explore), and live Realtime change subscriptions.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"bin": {
|