@opencorelabs/lucidity 0.2.0 → 0.3.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 (70) hide show
  1. package/README.md +29 -34
  2. package/bin/lucidity.js +2 -0
  3. package/dist/config.d.ts +2 -0
  4. package/dist/config.d.ts.map +1 -1
  5. package/dist/config.js +1 -0
  6. package/dist/index.js +25 -8
  7. package/dist/mcp/clients.d.ts +21 -0
  8. package/dist/mcp/clients.d.ts.map +1 -0
  9. package/dist/mcp/clients.js +193 -0
  10. package/dist/mcp/config.d.ts +2 -1
  11. package/dist/mcp/config.d.ts.map +1 -1
  12. package/dist/mcp/paired.d.ts +2 -0
  13. package/dist/mcp/paired.d.ts.map +1 -0
  14. package/dist/mcp/paired.js +20 -0
  15. package/dist/mcp/pairedConfig.d.ts +3 -0
  16. package/dist/mcp/pairedConfig.d.ts.map +1 -0
  17. package/dist/mcp/pairedConfig.js +33 -0
  18. package/dist/setup/page.d.ts +3 -0
  19. package/dist/setup/page.d.ts.map +1 -0
  20. package/dist/setup/page.js +120 -0
  21. package/dist/setup/server.d.ts +26 -0
  22. package/dist/setup/server.d.ts.map +1 -0
  23. package/dist/setup/server.js +398 -0
  24. package/package.json +1 -1
  25. package/src/config.ts +3 -0
  26. package/src/index.ts +41 -24
  27. package/src/mcp/clients.ts +269 -0
  28. package/src/mcp/config.ts +2 -1
  29. package/src/mcp/paired.ts +22 -0
  30. package/src/mcp/pairedConfig.ts +44 -0
  31. package/src/setup/page.ts +122 -0
  32. package/src/setup/server.ts +483 -0
  33. package/vendor/mcp-server/README.md +125 -48
  34. package/vendor/mcp-server/dist/index.js +11 -5
  35. package/vendor/mcp-server/dist/tools/comments.d.ts.map +1 -1
  36. package/vendor/mcp-server/dist/tools/comments.js +16 -1
  37. package/vendor/mcp-server/dist/tools/memory.d.ts +2 -2
  38. package/vendor/mcp-server/dist/tools/memory.d.ts.map +1 -1
  39. package/vendor/mcp-server/dist/tools/memory.js +24 -14
  40. package/vendor/mcp-server/dist/tools/milestones.d.ts.map +1 -1
  41. package/vendor/mcp-server/dist/tools/milestones.js +30 -0
  42. package/vendor/mcp-server/dist/tools/notes.d.ts.map +1 -1
  43. package/vendor/mcp-server/dist/tools/notes.js +30 -5
  44. package/vendor/mcp-server/dist/tools/projects.d.ts.map +1 -1
  45. package/vendor/mcp-server/dist/tools/projects.js +15 -0
  46. package/vendor/mcp-server/dist/tools/queries.d.ts.map +1 -1
  47. package/vendor/mcp-server/dist/tools/queries.js +27 -2
  48. package/vendor/mcp-server/dist/tools/tasks.d.ts.map +1 -1
  49. package/vendor/mcp-server/dist/tools/tasks.js +37 -0
  50. package/vendor/mcp-server/package.json +1 -1
  51. package/vendor/mcp-server/src/index.ts +19 -6
  52. package/vendor/mcp-server/src/tools/comments.ts +19 -1
  53. package/vendor/mcp-server/src/tools/memory.ts +26 -12
  54. package/vendor/mcp-server/src/tools/milestones.ts +36 -0
  55. package/vendor/mcp-server/src/tools/notes.ts +35 -4
  56. package/vendor/mcp-server/src/tools/projects.ts +18 -0
  57. package/vendor/mcp-server/src/tools/queries.ts +30 -0
  58. package/vendor/mcp-server/src/tools/tasks.ts +44 -0
  59. package/vendor/shared/dist/brandArtwork.d.ts +4 -0
  60. package/vendor/shared/dist/brandArtwork.d.ts.map +1 -0
  61. package/vendor/shared/dist/brandArtwork.js +7 -0
  62. package/vendor/shared/dist/index.d.ts +1 -0
  63. package/vendor/shared/dist/index.d.ts.map +1 -1
  64. package/vendor/shared/dist/index.js +1 -0
  65. package/vendor/shared/dist/setupAppearance.d.ts +6 -0
  66. package/vendor/shared/dist/setupAppearance.d.ts.map +1 -0
  67. package/vendor/shared/dist/setupAppearance.js +17 -0
  68. package/vendor/shared/src/brandArtwork.ts +7 -0
  69. package/vendor/shared/src/index.ts +1 -0
  70. package/vendor/shared/src/setupAppearance.ts +32 -0
@@ -1,4 +1,5 @@
1
1
  #!/usr/bin/env node
2
+ import { readFileSync } from 'node:fs';
2
3
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
3
4
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
5
  import { registerTaskTools } from './tools/tasks.js';
@@ -8,9 +9,14 @@ import { registerMilestoneTools } from './tools/milestones.js';
8
9
  import { registerCommentTools } from './tools/comments.js';
9
10
  import { registerNoteTools } from './tools/notes.js';
10
11
  import { registerMemoryTools } from './tools/memory.js';
11
- const server = new McpServer({
12
- name: 'lucidity',
13
- version: '0.1.0',
12
+ const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
13
+ const server = new McpServer({ name: 'lucidity', version }, {
14
+ instructions: 'Manage Lucidity tasks, projects, milestones, comments, and local notes. ' +
15
+ 'Use list/search tools to resolve IDs, then get_task for full details. ' +
16
+ 'Filter and paginate list_tasks; use get_task_stats for counts. ' +
17
+ 'complete_task toggles completion and advances recurring tasks; check state before repeating it. ' +
18
+ "Note paths are relative to the configured vault. Memory tools, when available, share Lucid's MEMORY.md. " +
19
+ 'For AI-authored comments, source="claude" is the legacy API value for every AI client.',
14
20
  });
15
21
  registerTaskTools(server);
16
22
  registerProjectTools(server);
@@ -19,8 +25,8 @@ registerMilestoneTools(server);
19
25
  registerCommentTools(server);
20
26
  registerNoteTools(server);
21
27
  // Lucid's own long-term memory — only when the daemon runs us with a vault
22
- // (`LUCIDITY_VAULT_PATH`). The standalone/Claude-Desktop server has no vault.
23
- if (process.env['LUCIDITY_VAULT_PATH'])
28
+ // (`LUCIDITY_VAULT_PATH`). Standalone clients can opt in with the same variable.
29
+ if (process.env['LUCIDITY_VAULT_PATH']?.trim())
24
30
  registerMemoryTools(server);
25
31
  const transport = new StdioServerTransport();
26
32
  await server.connect(transport);
@@ -1 +1 @@
1
- {"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/tools/comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoBzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,QAoFrD"}
1
+ {"version":3,"file":"comments.d.ts","sourceRoot":"","sources":["../../src/tools/comments.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAoBzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,QAsGrD"}
@@ -8,6 +8,11 @@ function formatComment(c) {
8
8
  export function registerCommentTools(server) {
9
9
  server.tool('list_comments', 'List comments on a task.', {
10
10
  task_id: z.string().describe('Task ID to list comments for'),
11
+ }, {
12
+ readOnlyHint: true,
13
+ destructiveHint: false,
14
+ idempotentHint: true,
15
+ openWorldHint: false,
11
16
  }, async ({ task_id }) => {
12
17
  const comments = await apiRequest(`/api/tasks/${task_id}/comments`);
13
18
  const summary = comments.length === 0
@@ -28,7 +33,12 @@ export function registerCommentTools(server) {
28
33
  source: z
29
34
  .enum(['user', 'claude'])
30
35
  .optional()
31
- .describe("Comment source: 'user' (default) or 'claude' for AI-generated comments"),
36
+ .describe("Comment source: 'user' (default) for human-authored text; 'claude' is the legacy API value for AI-generated comments from any client, including Codex"),
37
+ }, {
38
+ readOnlyHint: false,
39
+ destructiveHint: false,
40
+ idempotentHint: false,
41
+ openWorldHint: false,
32
42
  }, async ({ task_id, content, source }) => {
33
43
  const body = { content };
34
44
  if (source)
@@ -49,6 +59,11 @@ export function registerCommentTools(server) {
49
59
  server.tool('delete_comment', 'Delete a comment from a task. Get the comment_id from list_comments or get_task.', {
50
60
  task_id: z.string().describe('Task ID the comment belongs to'),
51
61
  comment_id: z.string().describe('Comment ID to delete'),
62
+ }, {
63
+ readOnlyHint: false,
64
+ destructiveHint: true,
65
+ idempotentHint: false,
66
+ openWorldHint: false,
52
67
  }, async ({ task_id, comment_id }) => {
53
68
  await apiRequest(`/api/tasks/${task_id}/comments/${comment_id}`, {
54
69
  method: 'DELETE',
@@ -13,8 +13,8 @@ export declare function forgetFacts(existing: string[], match: string): {
13
13
  /**
14
14
  * Lucid's durable long-term memory (the vault `MEMORY.md`). Registered only when
15
15
  * `LUCIDITY_VAULT_PATH` is set (i.e. the daemon runs this server with the `memory`
16
- * capability on) — the standalone/Claude-Desktop server has no vault and no memory
17
- * tools. Facts are the same bullet-list the daily reflection maintains, so what
16
+ * capability on). Standalone clients can opt in with the same variable.
17
+ * Facts are the same bullet-list the daily reflection maintains, so what
18
18
  * chat remembers and forgets flows straight into future briefings.
19
19
  */
20
20
  export declare function registerMemoryTools(server: McpServer): void;
@@ -1 +1 @@
1
- {"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/tools/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAuCzE;gFACgF;AAChF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAKpG;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKnG;AAoBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QA4CpD"}
1
+ {"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/tools/memory.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmCzE;gFACgF;AAChF,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAKpG;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG;IAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAKnG;AAoBD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,QA8DpD"}
@@ -19,12 +19,7 @@ function readFacts(root) {
19
19
  const file = memoryFile(root);
20
20
  if (!existsSync(file))
21
21
  return [];
22
- try {
23
- return parseFacts(readFileSync(file, 'utf8'));
24
- }
25
- catch {
26
- return [];
27
- }
22
+ return parseFacts(readFileSync(file, 'utf8'));
28
23
  }
29
24
  /** Full-file rewrite, matching the daemon's vault.writeMemoryFacts + post-briefing
30
25
  * reflection so both writers produce an identical MEMORY.md. */
@@ -49,32 +44,37 @@ export function forgetFacts(existing, match) {
49
44
  const kept = existing.filter((f) => !f.toLowerCase().includes(needle));
50
45
  return { facts: kept, removed: existing.length - kept.length };
51
46
  }
52
- function text(body) {
53
- return { content: [{ type: 'text', text: body }] };
47
+ function text(body, isError = false) {
48
+ return { content: [{ type: 'text', text: body }], isError };
54
49
  }
55
50
  /** Runs `fn` with the resolved vault root, turning a missing config or filesystem
56
- * error into a plain message rather than crashing the server. */
51
+ * error into an MCP tool error rather than crashing the server. */
57
52
  function withMemory(fn) {
58
53
  const root = getVaultPath();
59
54
  if (!root) {
60
- return text('Memory is not available in this session (no vault is configured).');
55
+ return text('Memory is not available in this session (no vault is configured).', true);
61
56
  }
62
57
  try {
63
58
  return text(fn(root));
64
59
  }
65
60
  catch (err) {
66
- return text(`Error: ${err instanceof Error ? err.message : String(err)}`);
61
+ return text(`Error: ${err instanceof Error ? err.message : String(err)}`, true);
67
62
  }
68
63
  }
69
64
  /**
70
65
  * Lucid's durable long-term memory (the vault `MEMORY.md`). Registered only when
71
66
  * `LUCIDITY_VAULT_PATH` is set (i.e. the daemon runs this server with the `memory`
72
- * capability on) — the standalone/Claude-Desktop server has no vault and no memory
73
- * tools. Facts are the same bullet-list the daily reflection maintains, so what
67
+ * capability on). Standalone clients can opt in with the same variable.
68
+ * Facts are the same bullet-list the daily reflection maintains, so what
74
69
  * chat remembers and forgets flows straight into future briefings.
75
70
  */
76
71
  export function registerMemoryTools(server) {
77
- server.tool('read_memory', "Read Lucid's durable long-term memory — the facts it remembers about the user across sessions. Returns the current bullet list.", {}, async () => withMemory((root) => {
72
+ server.tool('read_memory', "Read Lucid's durable long-term memory — the facts it remembers about the user across sessions. Returns the current bullet list.", {}, {
73
+ readOnlyHint: true,
74
+ destructiveHint: false,
75
+ idempotentHint: true,
76
+ openWorldHint: false,
77
+ }, async () => withMemory((root) => {
78
78
  const facts = readFacts(root);
79
79
  if (!facts.length)
80
80
  return 'Memory is empty.';
@@ -82,6 +82,11 @@ export function registerMemoryTools(server) {
82
82
  }));
83
83
  server.tool('remember', 'Save a durable fact to long-term memory so it persists across future sessions and briefings. Use for stable facts about the user or their work, not transient chatter. Deduplicated automatically.', {
84
84
  fact: z.string().describe('A single durable fact to remember (one sentence).'),
85
+ }, {
86
+ readOnlyHint: false,
87
+ destructiveHint: true,
88
+ idempotentHint: false,
89
+ openWorldHint: false,
85
90
  }, async ({ fact }) => withMemory((root) => {
86
91
  const clean = fact.trim();
87
92
  if (!clean)
@@ -92,6 +97,11 @@ export function registerMemoryTools(server) {
92
97
  }));
93
98
  server.tool('forget', 'Remove durable facts from long-term memory. Every remembered fact containing the match text (case-insensitive) is dropped. Use to correct or clear stale/wrong facts so they stop resurfacing in briefings.', {
94
99
  match: z.string().describe('Text to match; each remembered fact containing it (case-insensitive) is removed.'),
100
+ }, {
101
+ readOnlyHint: false,
102
+ destructiveHint: true,
103
+ idempotentHint: false,
104
+ openWorldHint: false,
95
105
  }, async ({ match }) => withMemory((root) => {
96
106
  if (!match.trim())
97
107
  return 'Nothing to forget (empty match).';
@@ -1 +1 @@
1
- {"version":3,"file":"milestones.d.ts","sourceRoot":"","sources":["../../src/tools/milestones.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsCzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QA+KvD"}
1
+ {"version":3,"file":"milestones.d.ts","sourceRoot":"","sources":["../../src/tools/milestones.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAsCzE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,SAAS,QAmNvD"}
@@ -14,6 +14,11 @@ function progressBar(percent, width = 20) {
14
14
  export function registerMilestoneTools(server) {
15
15
  server.tool('list_milestones', 'List milestones, optionally filtered by project.', {
16
16
  project_id: z.string().optional().describe('Filter by project ID'),
17
+ }, {
18
+ readOnlyHint: true,
19
+ destructiveHint: false,
20
+ idempotentHint: true,
21
+ openWorldHint: false,
17
22
  }, async ({ project_id }) => {
18
23
  const qs = project_id ? `?project_id=${project_id}` : '';
19
24
  const milestones = await apiRequest(`/api/milestones${qs}`);
@@ -39,6 +44,11 @@ export function registerMilestoneTools(server) {
39
44
  .string()
40
45
  .optional()
41
46
  .describe('Due date in ISO 8601 format (e.g. 2025-06-30)'),
47
+ }, {
48
+ readOnlyHint: false,
49
+ destructiveHint: false,
50
+ idempotentHint: false,
51
+ openWorldHint: false,
42
52
  }, async ({ project_id, name, description, due_date }) => {
43
53
  const body = { projectId: project_id, name };
44
54
  if (description)
@@ -66,6 +76,11 @@ export function registerMilestoneTools(server) {
66
76
  .string()
67
77
  .optional()
68
78
  .describe('New due date in ISO 8601 format'),
79
+ }, {
80
+ readOnlyHint: false,
81
+ destructiveHint: true,
82
+ idempotentHint: false,
83
+ openWorldHint: false,
69
84
  }, async ({ id, name, description, due_date }) => {
70
85
  const body = {};
71
86
  if (name)
@@ -89,6 +104,11 @@ export function registerMilestoneTools(server) {
89
104
  });
90
105
  server.tool('delete_milestone', 'Delete a milestone. Tasks assigned to this milestone will be unlinked but not deleted.', {
91
106
  id: z.string().describe('Milestone ID to delete'),
107
+ }, {
108
+ readOnlyHint: false,
109
+ destructiveHint: true,
110
+ idempotentHint: false,
111
+ openWorldHint: false,
92
112
  }, async ({ id }) => {
93
113
  await apiRequest(`/api/milestones/${id}`, { method: 'DELETE' });
94
114
  return {
@@ -108,6 +128,11 @@ export function registerMilestoneTools(server) {
108
128
  .array(z.string())
109
129
  .min(1)
110
130
  .describe('Milestone IDs to merge in and delete'),
131
+ }, {
132
+ readOnlyHint: false,
133
+ destructiveHint: true,
134
+ idempotentHint: false,
135
+ openWorldHint: false,
111
136
  }, async ({ target_milestone_id, source_milestone_ids }) => {
112
137
  const result = await apiRequest('/api/milestones/merge', {
113
138
  method: 'POST',
@@ -127,6 +152,11 @@ export function registerMilestoneTools(server) {
127
152
  });
128
153
  server.tool('get_milestone_progress', 'Get completion progress for a milestone. Shows task counts by status and a visual progress bar.', {
129
154
  id: z.string().describe('Milestone ID'),
155
+ }, {
156
+ readOnlyHint: true,
157
+ destructiveHint: false,
158
+ idempotentHint: true,
159
+ openWorldHint: false,
130
160
  }, async ({ id }) => {
131
161
  const progress = await apiRequest(`/api/milestones/${id}/progress`);
132
162
  const bar = progressBar(progress.percent);
@@ -1 +1 @@
1
- {"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/tools/notes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA8CzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QAyGlD"}
1
+ {"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/tools/notes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA+CzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QAuIlD"}
@@ -10,25 +10,25 @@ function getVaultPath() {
10
10
  const p = process.env['LUCIDITY_NOTES_PATH'];
11
11
  return p && p.trim() ? expandHome(p.trim()) : null;
12
12
  }
13
- function text(body) {
14
- return { content: [{ type: 'text', text: body }] };
13
+ function text(body, isError = false) {
14
+ return { content: [{ type: 'text', text: body }], isError };
15
15
  }
16
16
  /**
17
17
  * Runs `fn` against the configured vault, turning a missing config or any
18
- * filesystem/validation error into a plain text message rather than crashing
18
+ * filesystem/validation error into an MCP tool error rather than crashing
19
19
  * the server — so the task tools keep working even when notes aren't set up.
20
20
  */
21
21
  async function withVault(fn) {
22
22
  const root = getVaultPath();
23
23
  if (!root) {
24
24
  return text('Notes are not configured. Set the LUCIDITY_NOTES_PATH environment variable ' +
25
- 'to your markdown vault folder and restart the MCP server.');
25
+ 'to your markdown vault folder and restart the MCP server.', true);
26
26
  }
27
27
  try {
28
28
  return text(await fn(root));
29
29
  }
30
30
  catch (err) {
31
- return text(`Error: ${err instanceof Error ? err.message : String(err)}`);
31
+ return text(`Error: ${err instanceof Error ? err.message : String(err)}`, true);
32
32
  }
33
33
  }
34
34
  export function registerNoteTools(server) {
@@ -38,6 +38,11 @@ export function registerNoteTools(server) {
38
38
  .optional()
39
39
  .describe('Limit to a subfolder (relative to the vault root)'),
40
40
  limit: z.number().optional().describe('Max notes to return (default 50)'),
41
+ }, {
42
+ readOnlyHint: true,
43
+ destructiveHint: false,
44
+ idempotentHint: true,
45
+ openWorldHint: false,
41
46
  }, async ({ folder, limit }) => withVault((root) => {
42
47
  const notes = listNotes(root, { folder, limit });
43
48
  if (notes.length === 0)
@@ -50,6 +55,11 @@ export function registerNoteTools(server) {
50
55
  path: z
51
56
  .string()
52
57
  .describe('Note path relative to the vault root (e.g. "Projects/ideas.md")'),
58
+ }, {
59
+ readOnlyHint: true,
60
+ destructiveHint: false,
61
+ idempotentHint: true,
62
+ openWorldHint: false,
53
63
  }, async ({ path }) => withVault((root) => {
54
64
  const note = readNote(root, path);
55
65
  return `# ${note.title}\n(${note.path}, modified ${note.mtime})\n\n${note.content}`;
@@ -57,6 +67,11 @@ export function registerNoteTools(server) {
57
67
  server.tool('search_notes', 'Search notes by keyword (naive case-insensitive substring over filenames and bodies).', {
58
68
  query: z.string().describe('Text to search for'),
59
69
  limit: z.number().optional().describe('Max results (default 20)'),
70
+ }, {
71
+ readOnlyHint: true,
72
+ destructiveHint: false,
73
+ idempotentHint: true,
74
+ openWorldHint: false,
60
75
  }, async ({ query, limit }) => withVault((root) => {
61
76
  const hits = searchNotes(root, query, { limit });
62
77
  if (hits.length === 0)
@@ -74,6 +89,11 @@ export function registerNoteTools(server) {
74
89
  .enum(['create', 'append', 'overwrite'])
75
90
  .optional()
76
91
  .describe('Write mode (default: create)'),
92
+ }, {
93
+ readOnlyHint: false,
94
+ destructiveHint: true,
95
+ idempotentHint: false,
96
+ openWorldHint: false,
77
97
  }, async ({ path, content, mode }) => withVault((root) => {
78
98
  const note = writeNote(root, path, content, mode ?? 'create');
79
99
  return `Wrote ${note.path} (${mode ?? 'create'}).`;
@@ -90,6 +110,11 @@ export function registerNoteTools(server) {
90
110
  .boolean()
91
111
  .optional()
92
112
  .describe('Replace every occurrence of oldString (default: false)'),
113
+ }, {
114
+ readOnlyHint: false,
115
+ destructiveHint: true,
116
+ idempotentHint: false,
117
+ openWorldHint: false,
93
118
  }, async ({ path, oldString, newString, replaceAll }) => withVault((root) => {
94
119
  const note = editNote(root, path, oldString, newString, replaceAll ?? false);
95
120
  return `Edited ${note.path}.`;
@@ -1 +1 @@
1
- {"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/tools/projects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkDzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,QAmIrD"}
1
+ {"version":3,"file":"projects.d.ts","sourceRoot":"","sources":["../../src/tools/projects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAkDzE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,QAqJrD"}
@@ -33,6 +33,11 @@ export function registerProjectTools(server) {
33
33
  .boolean()
34
34
  .optional()
35
35
  .describe('Include archived projects (default: false)'),
36
+ }, {
37
+ readOnlyHint: true,
38
+ destructiveHint: false,
39
+ idempotentHint: true,
40
+ openWorldHint: false,
36
41
  }, async ({ include_archived }) => {
37
42
  const [allProjects, orgs] = await Promise.all([
38
43
  apiRequest('/api/projects'),
@@ -70,6 +75,11 @@ export function registerProjectTools(server) {
70
75
  .enum(['deep', 'light', 'none'])
71
76
  .optional()
72
77
  .describe('AI review depth: deep (dev projects), light (default), none (skip)'),
78
+ }, {
79
+ readOnlyHint: false,
80
+ destructiveHint: false,
81
+ idempotentHint: false,
82
+ openWorldHint: false,
73
83
  }, async ({ name, color, description, organization, ai_review_depth }) => {
74
84
  const body = { name };
75
85
  if (color)
@@ -111,6 +121,11 @@ export function registerProjectTools(server) {
111
121
  .enum(['deep', 'light', 'none'])
112
122
  .optional()
113
123
  .describe('AI review depth: deep, light, or none'),
124
+ }, {
125
+ readOnlyHint: false,
126
+ destructiveHint: true,
127
+ idempotentHint: false,
128
+ openWorldHint: false,
114
129
  }, async ({ id, name, color, description, is_archived, ai_review_depth }) => {
115
130
  const body = {};
116
131
  if (name)
@@ -1 +1 @@
1
- {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/tools/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmDzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QAsNnD"}
1
+ {"version":3,"file":"queries.d.ts","sourceRoot":"","sources":["../../src/tools/queries.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAmDzE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,QAoPnD"}
@@ -16,7 +16,12 @@ function formatTask(t) {
16
16
  return `${status} ${t.title}${num}${due}${recurring}`;
17
17
  }
18
18
  export function registerQueryTools(server) {
19
- server.tool('get_today', "Get today's tasks including overdue items. Shows non-completed root tasks due today or earlier.", {}, async () => {
19
+ server.tool('get_today', "Get today's tasks including overdue items. Shows non-completed root tasks due today or earlier.", {}, {
20
+ readOnlyHint: true,
21
+ destructiveHint: false,
22
+ idempotentHint: true,
23
+ openWorldHint: false,
24
+ }, async () => {
20
25
  const tasks = await apiRequest('/api/tasks/today');
21
26
  const today = new Date();
22
27
  today.setHours(0, 0, 0, 0);
@@ -43,7 +48,12 @@ export function registerQueryTools(server) {
43
48
  content: [{ type: 'text', text: summary }],
44
49
  };
45
50
  });
46
- server.tool('get_week', "Get this week's tasks (Monday to Sunday). Shows non-completed root tasks grouped by day.", {}, async () => {
51
+ server.tool('get_week', "Get this week's tasks (Monday to Sunday). Shows non-completed root tasks grouped by day.", {}, {
52
+ readOnlyHint: true,
53
+ destructiveHint: false,
54
+ idempotentHint: true,
55
+ openWorldHint: false,
56
+ }, async () => {
47
57
  const tasks = await apiRequest('/api/tasks/week');
48
58
  const days = [
49
59
  'Monday',
@@ -90,6 +100,11 @@ export function registerQueryTools(server) {
90
100
  });
91
101
  server.tool('search', 'Search tasks and projects by keyword. Searches task titles, descriptions, comment content, and project names. Each task result includes which field matched and a snippet of the surrounding text.', {
92
102
  query: z.string().describe('Search query'),
103
+ }, {
104
+ readOnlyHint: true,
105
+ destructiveHint: false,
106
+ idempotentHint: true,
107
+ openWorldHint: false,
93
108
  }, async ({ query }) => {
94
109
  const result = await apiRequest(`/api/search?q=${encodeURIComponent(query)}`);
95
110
  let summary = `🔍 Search results for "${query}":\n\n`;
@@ -124,6 +139,11 @@ export function registerQueryTools(server) {
124
139
  .string()
125
140
  .optional()
126
141
  .describe('Scope stats to a specific project ID'),
142
+ }, {
143
+ readOnlyHint: true,
144
+ destructiveHint: false,
145
+ idempotentHint: true,
146
+ openWorldHint: false,
127
147
  }, async ({ project_id }) => {
128
148
  const qs = project_id ? `?project_id=${project_id}` : '';
129
149
  const stats = await apiRequest(`/api/tasks/stats${qs}`);
@@ -141,6 +161,11 @@ export function registerQueryTools(server) {
141
161
  .number()
142
162
  .optional()
143
163
  .describe('Max results to return (default 50)'),
164
+ }, {
165
+ readOnlyHint: true,
166
+ destructiveHint: false,
167
+ idempotentHint: true,
168
+ openWorldHint: false,
144
169
  }, async ({ project_id, limit }) => {
145
170
  const params = new URLSearchParams();
146
171
  if (project_id)
@@ -1 +1 @@
1
- {"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyEzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QAuWlD"}
1
+ {"version":3,"file":"tasks.d.ts","sourceRoot":"","sources":["../../src/tools/tasks.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAyEzE,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,QAmZlD"}
@@ -54,11 +54,17 @@ export function registerTaskTools(server) {
54
54
  .number()
55
55
  .optional()
56
56
  .describe('Task number within the project (the #N shown in listings)'),
57
+ }, {
58
+ readOnlyHint: true,
59
+ destructiveHint: false,
60
+ idempotentHint: true,
61
+ openWorldHint: false,
57
62
  }, async ({ id, project_id, task_number }) => {
58
63
  let taskId = id;
59
64
  if (!taskId) {
60
65
  if (!project_id || task_number === undefined) {
61
66
  return {
67
+ isError: true,
62
68
  content: [
63
69
  {
64
70
  type: 'text',
@@ -74,6 +80,7 @@ export function registerTaskTools(server) {
74
80
  const found = await apiRequest(`/api/tasks?${params}`);
75
81
  if (!found.tasks.length) {
76
82
  return {
83
+ isError: true,
77
84
  content: [
78
85
  {
79
86
  type: 'text',
@@ -145,6 +152,11 @@ export function registerTaskTools(server) {
145
152
  .number()
146
153
  .optional()
147
154
  .describe('Number of results to skip (default 0)'),
155
+ }, {
156
+ readOnlyHint: true,
157
+ destructiveHint: false,
158
+ idempotentHint: true,
159
+ openWorldHint: false,
148
160
  }, async ({ status, project_id, milestone_id, project, milestone, task_number, root_only, due_before, due_after, created_after, created_before, sort_by, limit, offset }) => {
149
161
  const projectFilter = project_id ?? project;
150
162
  const milestoneFilter = milestone_id ?? milestone;
@@ -220,6 +232,11 @@ export function registerTaskTools(server) {
220
232
  .enum(['daily', 'weekly', 'monthly', 'yearly'])
221
233
  .optional()
222
234
  .describe('Recurring frequency (requires due_date)'),
235
+ }, {
236
+ readOnlyHint: false,
237
+ destructiveHint: false,
238
+ idempotentHint: false,
239
+ openWorldHint: false,
223
240
  }, async ({ title, description, project_id, milestone_id, parent_task_id, due_date, priority, recurring_frequency, }) => {
224
241
  const body = { title };
225
242
  if (description)
@@ -271,6 +288,11 @@ export function registerTaskTools(server) {
271
288
  .enum(['daily', 'weekly', 'monthly', 'yearly'])
272
289
  .optional()
273
290
  .describe('New recurring frequency'),
291
+ }, {
292
+ readOnlyHint: false,
293
+ destructiveHint: true,
294
+ idempotentHint: false,
295
+ openWorldHint: false,
274
296
  }, async ({ id, title, description, status, project_id, milestone_id, due_date, priority, recurring_frequency, }) => {
275
297
  const body = {};
276
298
  if (title)
@@ -304,6 +326,11 @@ export function registerTaskTools(server) {
304
326
  });
305
327
  server.tool('complete_task', 'Toggle task completion. For recurring tasks, this advances to the next occurrence.', {
306
328
  id: z.string().describe('Task ID to complete/uncomplete'),
329
+ }, {
330
+ readOnlyHint: false,
331
+ destructiveHint: true,
332
+ idempotentHint: false,
333
+ openWorldHint: false,
307
334
  }, async ({ id }) => {
308
335
  const task = await apiRequest(`/api/tasks/${id}/complete`, {
309
336
  method: 'PATCH',
@@ -320,6 +347,11 @@ export function registerTaskTools(server) {
320
347
  });
321
348
  server.tool('delete_task', 'Delete a task and all its subtasks.', {
322
349
  id: z.string().describe('Task ID to delete'),
350
+ }, {
351
+ readOnlyHint: false,
352
+ destructiveHint: true,
353
+ idempotentHint: false,
354
+ openWorldHint: false,
323
355
  }, async ({ id }) => {
324
356
  await apiRequest(`/api/tasks/${id}`, { method: 'DELETE' });
325
357
  return {
@@ -333,6 +365,11 @@ export function registerTaskTools(server) {
333
365
  });
334
366
  server.tool('mark_task_reviewed', 'Mark a task as reviewed by AI. Sets reviewedAt timestamp so it won\'t appear in unreviewed lists.', {
335
367
  id: z.string().describe('Task ID to mark as reviewed'),
368
+ }, {
369
+ readOnlyHint: false,
370
+ destructiveHint: false,
371
+ idempotentHint: false,
372
+ openWorldHint: false,
336
373
  }, async ({ id }) => {
337
374
  const task = await apiRequest(`/api/tasks/${id}/review`, {
338
375
  method: 'PATCH',
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@lucidity/mcp-server",
3
- "version": "0.1.0",
3
+ "version": "0.3.0",
4
4
  "private": true,
5
5
  "type": "module",
6
6
  "bin": {
@@ -1,5 +1,6 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ import { readFileSync } from 'node:fs';
3
4
  import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
4
5
  import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
5
6
  import { registerTaskTools } from './tools/tasks.js';
@@ -10,10 +11,22 @@ import { registerCommentTools } from './tools/comments.js';
10
11
  import { registerNoteTools } from './tools/notes.js';
11
12
  import { registerMemoryTools } from './tools/memory.js';
12
13
 
13
- const server = new McpServer({
14
- name: 'lucidity',
15
- version: '0.1.0',
16
- });
14
+ const { version } = JSON.parse(
15
+ readFileSync(new URL('../package.json', import.meta.url), 'utf8'),
16
+ ) as { version: string };
17
+
18
+ const server = new McpServer(
19
+ { name: 'lucidity', version },
20
+ {
21
+ instructions:
22
+ 'Manage Lucidity tasks, projects, milestones, comments, and local notes. ' +
23
+ 'Use list/search tools to resolve IDs, then get_task for full details. ' +
24
+ 'Filter and paginate list_tasks; use get_task_stats for counts. ' +
25
+ 'complete_task toggles completion and advances recurring tasks; check state before repeating it. ' +
26
+ "Note paths are relative to the configured vault. Memory tools, when available, share Lucid's MEMORY.md. " +
27
+ 'For AI-authored comments, source="claude" is the legacy API value for every AI client.',
28
+ },
29
+ );
17
30
 
18
31
  registerTaskTools(server);
19
32
  registerProjectTools(server);
@@ -22,8 +35,8 @@ registerMilestoneTools(server);
22
35
  registerCommentTools(server);
23
36
  registerNoteTools(server);
24
37
  // Lucid's own long-term memory — only when the daemon runs us with a vault
25
- // (`LUCIDITY_VAULT_PATH`). The standalone/Claude-Desktop server has no vault.
26
- if (process.env['LUCIDITY_VAULT_PATH']) registerMemoryTools(server);
38
+ // (`LUCIDITY_VAULT_PATH`). Standalone clients can opt in with the same variable.
39
+ if (process.env['LUCIDITY_VAULT_PATH']?.trim()) registerMemoryTools(server);
27
40
 
28
41
  const transport = new StdioServerTransport();
29
42
  await server.connect(transport);
@@ -25,6 +25,12 @@ export function registerCommentTools(server: McpServer) {
25
25
  {
26
26
  task_id: z.string().describe('Task ID to list comments for'),
27
27
  },
28
+ {
29
+ readOnlyHint: true,
30
+ destructiveHint: false,
31
+ idempotentHint: true,
32
+ openWorldHint: false,
33
+ },
28
34
  async ({ task_id }) => {
29
35
  const comments = await apiRequest<Comment[]>(
30
36
  `/api/tasks/${task_id}/comments`,
@@ -55,7 +61,13 @@ export function registerCommentTools(server: McpServer) {
55
61
  source: z
56
62
  .enum(['user', 'claude'])
57
63
  .optional()
58
- .describe("Comment source: 'user' (default) or 'claude' for AI-generated comments"),
64
+ .describe("Comment source: 'user' (default) for human-authored text; 'claude' is the legacy API value for AI-generated comments from any client, including Codex"),
65
+ },
66
+ {
67
+ readOnlyHint: false,
68
+ destructiveHint: false,
69
+ idempotentHint: false,
70
+ openWorldHint: false,
59
71
  },
60
72
  async ({ task_id, content, source }) => {
61
73
  const body: Record<string, unknown> = { content };
@@ -87,6 +99,12 @@ export function registerCommentTools(server: McpServer) {
87
99
  task_id: z.string().describe('Task ID the comment belongs to'),
88
100
  comment_id: z.string().describe('Comment ID to delete'),
89
101
  },
102
+ {
103
+ readOnlyHint: false,
104
+ destructiveHint: true,
105
+ idempotentHint: false,
106
+ openWorldHint: false,
107
+ },
90
108
  async ({ task_id, comment_id }) => {
91
109
  await apiRequest(`/api/tasks/${task_id}/comments/${comment_id}`, {
92
110
  method: 'DELETE',