@mayamemo/mcp 0.1.0 → 0.2.0

package/dist/bin.js

@@ -1,12 +1,14 @@
 #!/usr/bin/env node
 import { createHttpCallApi, createStdioRunner } from './stdio.js';
+import { resolveDefaultProjectId } from './project.js';
 const apiUrl = process.env.MAYAMEMO_API_URL ?? 'http://localhost:4000';
 const token = process.env.MAYAMEMO_TOKEN;
 if (!token) {
     process.stderr.write('mayamemo-mcp: MAYAMEMO_TOKEN is required (workspace API key, mm_sk_...).\n');
     process.exit(1);
 }
-process.stderr.write(`mayamemo-mcp: serving on stdio, API at ${apiUrl}\n`);
+const linked = resolveDefaultProjectId();
+process.stderr.write(`mayamemo-mcp: serving on stdio, API at ${apiUrl}${linked ? `, linked project ${linked}` : ' — no project linked to this folder'}\n`);
 createStdioRunner({
     input: process.stdin,
     output: process.stdout,

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './server.js';
 export * from './tools.js';
 export * from './stdio.js';
+export * from './project.js';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from './server.js';
 export * from './tools.js';
 export * from './stdio.js';
+export * from './project.js';

package/dist/project.d.ts

@@ -0,0 +1,12 @@
+export interface ProjectMapping {
+    projectId: string;
+    name?: string;
+    workspaceId?: string;
+    apiUrl?: string;
+}
+/** True for placeholder ids agents invent when they don't know the project. */
+export declare function isPlaceholderProjectId(value: string): boolean;
+/** Walk up from `startDir` looking for .mayamemo/project.json. */
+export declare function findMappedProjectId(startDir?: string): string | null;
+/** env override first, then the linked mapping; null when nothing is linked. */
+export declare function resolveDefaultProjectId(startDir?: string): string | null;

package/dist/project.js

@@ -0,0 +1,43 @@
+/**
+ * Default project resolution for the MCP server. When a tool call omits
+ * project_id, resolve the project linked to the working directory:
+ * MAYAMEMO_PROJECT_ID env first, then the nearest .mayamemo/project.json
+ * (written by `mayamemo init` / `mayamemo install`), walking up.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+const ZERO_UUID = /^0{8}-0{4}-0{4}-0{4}-0{12}$/;
+/** True for placeholder ids agents invent when they don't know the project. */
+export function isPlaceholderProjectId(value) {
+    return ZERO_UUID.test(value.trim());
+}
+/** Walk up from `startDir` looking for .mayamemo/project.json. */
+export function findMappedProjectId(startDir = process.cwd()) {
+    let dir = resolve(startDir);
+    for (;;) {
+        const candidate = join(dir, '.mayamemo', 'project.json');
+        if (existsSync(candidate)) {
+            try {
+                const parsed = JSON.parse(readFileSync(candidate, 'utf8'));
+                if (typeof parsed.projectId === 'string' && parsed.projectId.trim().length > 0) {
+                    return parsed.projectId.trim();
+                }
+            }
+            catch {
+                // Corrupt mapping — keep walking up.
+            }
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            return null;
+        dir = parent;
+    }
+}
+/** env override first, then the linked mapping; null when nothing is linked. */
+export function resolveDefaultProjectId(startDir) {
+    const env = process.env.MAYAMEMO_PROJECT_ID;
+    if (typeof env === 'string' && env.trim().length > 0 && !isPlaceholderProjectId(env)) {
+        return env.trim();
+    }
+    return findMappedProjectId(startDir);
+}

package/dist/tools.d.ts

@@ -12,6 +12,9 @@ export interface McpDeps {
         status: number;
         body: unknown;
     }>;
+    /** Hosted transports pin a default project (most recently active in the workspace)
+     * so remote agents can omit project_id entirely. */
+    fallbackProjectId?: string;
 }
 export interface McpToolResult {
     text: string;

package/dist/tools.js

@@ -4,6 +4,7 @@
  * V1 tools per docs/MCP.md: context_get, context_search, memory_search,
  * memory_save, project_state, checkpoint_create (unlocked at M06).
  */
+import { isPlaceholderProjectId, resolveDefaultProjectId } from './project.js';
 /** Thrown by handlers for invalid tool arguments → JSON-RPC -32602. */
 export class ToolInputError extends Error {
 }
@@ -60,6 +61,28 @@ function entityRefs(args, key, cap) {
     }
     return refs;
 }
+/** project_id is optional: an explicit value wins; otherwise fall back to the
+ * project linked to the working directory (MAYAMEMO_PROJECT_ID env or the
+ * nearest .mayamemo/project.json), then to the transport's fallback (hosted
+ * MCP pins the workspace's most recently active project). */
+function resolveProjectId(args, deps) {
+    const raw = args.project_id;
+    if (raw !== undefined && raw !== null) {
+        if (typeof raw !== 'string')
+            throw new ToolInputError('Argument project_id must be a string');
+        const trimmed = raw.trim();
+        if (trimmed.length > 0 && !isPlaceholderProjectId(trimmed))
+            return trimmed;
+    }
+    // Hosted transports pin their default first: on a shared server the process
+    // cwd/env is meaningless (it belongs to the server, not the caller).
+    if (deps.fallbackProjectId)
+        return deps.fallbackProjectId;
+    const mapped = resolveDefaultProjectId();
+    if (mapped)
+        return mapped;
+    throw new ToolInputError('No MayaMemo project is linked to this folder. Run `npx -y @mayamemo/cli init` (or `mayamemo install opencode`) in the repo to link one, pass project_id explicitly, or use the hosted MCP at mcp.mayamemo.com where your most recently active project is used by default.');
+}
 function apiErrorText(status, body) {
     const error = body.error;
     const code = error?.code ?? 'API_ERROR';
@@ -76,7 +99,7 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string', description: 'MayaMemo project id (from the project mapping)' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder (.mayamemo/project.json or MAYAMEMO_PROJECT_ID)' },
                 statement: { type: 'string', description: 'The durable claim, present tense' },
                 type: { type: 'string', description: 'Memory type' },
                 confidence: { type: 'number', description: '0..1 how strongly the evidence supports it' },
@@ -101,11 +124,11 @@ export const TOOLS = [
                     description: 'Optional code entities this memory is about (linked into the project graph)',
                 },
             },
-            required: ['project_id', 'statement', 'type'],
+            required: ['statement', 'type'],
         },
         async handler(args, deps) {
             const payload = {
-                project_id: requireString(args, 'project_id'),
+                project_id: resolveProjectId(args, deps),
                 statement: requireString(args, 'statement'),
                 type: requireString(args, 'type'),
             };
@@ -141,7 +164,7 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' },
                 query: { type: 'string', description: 'Natural-language search query (may embed a time phrase: "last week", "past 3 days", "since 2026-09-01")' },
                 status: { type: 'string', description: 'Optional memory status filter (default active)' },
                 limit: { type: 'number', description: 'Max results (default 8, max 25)' },
@@ -153,11 +176,11 @@ export const TOOLS = [
                 since: { type: 'string', description: 'Optional ISO datetime lower bound (memories created or changed after it)' },
                 until: { type: 'string', description: 'Optional ISO datetime upper bound' },
             },
-            required: ['project_id', 'query'],
+            required: ['query'],
         },
         async handler(args, deps) {
             const payload = {
-                project_id: requireString(args, 'project_id'),
+                project_id: resolveProjectId(args, deps),
                 query: requireString(args, 'query'),
             };
             const status = optionalString(args, 'status');
@@ -193,16 +216,16 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' },
                 query: { type: 'string', description: 'Task title / intent to compile context for' },
                 token_budget: { type: 'number', description: 'Hard token budget (default 4000, max 50000)' },
                 branch: { type: 'string', description: 'Current git branch (branch-matched context ranks higher)' },
             },
-            required: ['project_id', 'query'],
+            required: ['query'],
         },
         async handler(args, deps) {
             const payload = {
-                project_id: requireString(args, 'project_id'),
+                project_id: resolveProjectId(args, deps),
                 title: requireString(args, 'query'),
                 token_budget: Math.min(Math.max(optionalNumber(args, 'token_budget') ?? 4000, 64), 50000),
                 max_items: MAX_CONTEXT_ITEMS,
@@ -258,11 +281,11 @@ export const TOOLS = [
         description: 'Project state snapshot: counts, last session, last checkpoint, and recent ledger activity.',
         inputSchema: {
             type: 'object',
-            properties: { project_id: { type: 'string' } },
-            required: ['project_id'],
+            properties: { project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' } },
+            required: [],
         },
         async handler(args, deps) {
-            const projectId = requireString(args, 'project_id');
+            const projectId = resolveProjectId(args, deps);
             const res = await deps.callApi('GET', `/v1/projects/${encodeURIComponent(projectId)}/state`);
             if (res.status >= 400)
                 return apiErrorText(res.status, res.body);
@@ -286,7 +309,7 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' },
                 title: { type: 'string', description: 'Short checkpoint title' },
                 summary: { type: 'string', description: 'What was done and where things stand' },
                 next_steps: { type: 'array', items: { type: 'string' }, description: 'What the next agent should do' },
@@ -296,11 +319,11 @@ export const TOOLS = [
                 context_version_id: { type: 'string', description: 'Link an existing context version instead of compiling fresh' },
                 token_budget: { type: 'number', description: 'Budget for the fresh compile (default 6000)' },
             },
-            required: ['project_id', 'title', 'summary'],
+            required: ['title', 'summary'],
         },
         async handler(args, deps) {
             const payload = {
-                project_id: requireString(args, 'project_id'),
+                project_id: resolveProjectId(args, deps),
                 title: requireString(args, 'title'),
                 summary: requireString(args, 'summary'),
             };
@@ -337,7 +360,7 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string', description: 'MayaMemo project id' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' },
                 entities: {
                     type: 'array',
                     items: {
@@ -362,10 +385,10 @@ export const TOOLS = [
                     description: 'Relations between entities (max 100)',
                 },
             },
-            required: ['project_id'],
+            required: [],
         },
         async handler(args, deps) {
-            const payload = { project_id: requireString(args, 'project_id') };
+            const payload = { project_id: resolveProjectId(args, deps) };
             const entities = entityRefs(args, 'entities', 50);
             if (entities)
                 payload.entities = entities;
@@ -393,7 +416,7 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string', description: 'MayaMemo project id (required when listing)' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' },
                 q: { type: 'string', description: 'Name search (substring)' },
                 kind: { type: 'string', description: 'Filter by entity kind (file, module, symbol…)' },
                 entity_id: { type: 'string', description: 'Entity id — switches to neighbor mode' },
@@ -416,7 +439,7 @@ export const TOOLS = [
                     text: `Neighbors of ${graph.root.kind} ${graph.root.name} (${graph.nodes.length} nodes, ${graph.edges.length} edges${graph.truncated ? ', truncated' : ''}):\n${lines.join('\n')}`,
                 };
             }
-            const projectId = requireString(args, 'project_id');
+            const projectId = resolveProjectId(args, deps);
             const params = new URLSearchParams();
             const q = optionalString(args, 'q');
             if (q)
@@ -441,17 +464,17 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string', description: 'MayaMemo project id' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder' },
                 filename: { type: 'string', description: 'File name (drives text/code detection)' },
                 content_base64: { type: 'string', description: 'Raw file bytes, base64-encoded (max 10 MB decoded)' },
                 mime: { type: 'string', description: 'Optional MIME type (defaults to application/octet-stream)' },
                 memory_id: { type: 'string', description: 'Optional memory id to link the attachment to' },
             },
-            required: ['project_id', 'filename', 'content_base64'],
+            required: ['filename', 'content_base64'],
         },
         async handler(args, deps) {
             const payload = {
-                project_id: requireString(args, 'project_id'),
+                project_id: resolveProjectId(args, deps),
                 filename: requireString(args, 'filename'),
                 content_base64: requireString(args, 'content_base64'),
             };
@@ -536,15 +559,15 @@ export const TOOLS = [
         inputSchema: {
             type: 'object',
             properties: {
-                project_id: { type: 'string', description: 'MayaMemo project id (from the project mapping)' },
+                project_id: { type: 'string', description: 'Optional — defaults to the project linked to this folder (.mayamemo/project.json or MAYAMEMO_PROJECT_ID)' },
                 agent: { type: 'string', description: 'Your agent name (e.g. opencode, claude-code, codex)' },
                 branch: { type: 'string', description: 'Optional git branch this session works on' },
                 summary: { type: 'string', description: 'Optional one-line intent for the session' },
             },
-            required: ['project_id'],
+            required: [],
         },
         async handler(args, deps) {
-            const payload = { project_id: requireString(args, 'project_id') };
+            const payload = { project_id: resolveProjectId(args, deps) };
             const agent = optionalString(args, 'agent');
             if (agent)
                 payload.agent = agent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mayamemo/mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MayaMemo MCP server — durable project memory, checkpoints and handoffs for coding agents over stdio.",
   "license": "MIT",
   "type": "module",