@mayamemo/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MayaMemo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,31 @@
-# Temporary Holding Version
+# @mayamemo/mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MayaMemo MCP server — durable project memory, checkpoints and handoffs for coding agents, over stdio.
+
+## Use with opencode (zero install)
+
+```json
+{
+  "mcp": {
+    "mayamemo": {
+      "type": "local",
+      "command": ["npx", "-y", "@mayamemo/mcp"],
+      "environment": {
+        "MAYAMEMO_API_URL": "https://api.mayamemo.com",
+        "MAYAMEMO_TOKEN": "mm_sk_..."
+      },
+      "enabled": true
+    }
+  }
+}
+```
+
+Any MCP-capable host works the same way: `npx -y @mayamemo/mcp` with
+`MAYAMEMO_API_URL` + `MAYAMEMO_TOKEN` in the environment.
+
+Get a key at https://mayamemo.com → Account settings → Developers.
+
+Tools: `memory_save`, `memory_search`, `context_search`, `context_get`,
+`project_state`, `checkpoint_create`, `checkpoint_resume`, `entity_observe`,
+`graph_query`, `attachment_upload`, `attachment_describe`, `memory_feedback`,
+`session_start`, `session_end`.

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import { createHttpCallApi, createStdioRunner } from './stdio.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`);
+createStdioRunner({
+    input: process.stdin,
+    output: process.stdout,
+    deps: { callApi: createHttpCallApi(apiUrl, token) },
+    onError: (message) => process.stderr.write(`${message}\n`),
+});

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/server.d.ts

@@ -0,0 +1,25 @@
+import type { McpDeps, McpToolDefinition } from './tools.js';
+/**
+ * MCP protocol layer (JSON-RPC 2.0 over newline-delimited stdio).
+ * ADR-003: this package is an ADAPTER — it contains no domain logic; every tool
+ * delegates to the MayaMemo HTTP API through the injected `callApi` transport.
+ */
+export interface McpServerInfo {
+    name: string;
+    version: string;
+}
+export declare const MCP_SERVER_INFO: McpServerInfo;
+export declare const MCP_PROTOCOL_FALLBACK = "2025-06-18";
+export declare const SUPPORTED_PROTOCOL_VERSIONS: readonly ["2024-11-05", "2025-03-26", "2025-06-18", "2025-11-25", "2026-07-28"];
+export interface JsonRpcRequest {
+    jsonrpc: '2.0';
+    id?: number | string;
+    method: string;
+    params?: Record<string, unknown>;
+}
+export interface McpServer {
+    /** Handles one raw JSON-RPC line. Returns the serialized response, or null for notifications. */
+    handleMessage(line: string): Promise<string | null>;
+    tools: readonly McpToolDefinition[];
+}
+export declare function createMcpServer(deps: McpDeps): McpServer;

package/dist/server.js

@@ -0,0 +1,110 @@
+import { findTool, ToolInputError, TOOLS } from './tools.js';
+export const MCP_SERVER_INFO = { name: 'mayamemo-mcp', version: '0.1.0' };
+export const MCP_PROTOCOL_FALLBACK = '2025-06-18';
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+    '2024-11-05',
+    '2025-03-26',
+    '2025-06-18',
+    '2025-11-25',
+    '2026-07-28',
+];
+const PARSE_ERROR = -32700;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+function rpcSuccess(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+function rpcError(id, code, message) {
+    return { jsonrpc: '2.0', id, error: { code, message } };
+}
+export function createMcpServer(deps) {
+    async function dispatch(request) {
+        const { method } = request;
+        const id = request.id;
+        // Notifications (no id) never get a response.
+        if (method.startsWith('notifications/'))
+            return null;
+        if (method === 'initialize') {
+            const requested = request.params?.protocolVersion ?? MCP_PROTOCOL_FALLBACK;
+            const version = SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+                ? requested
+                : MCP_PROTOCOL_FALLBACK;
+            if (id === undefined)
+                return null;
+            return rpcSuccess(id, {
+                protocolVersion: version,
+                capabilities: { tools: {} },
+                serverInfo: MCP_SERVER_INFO,
+            });
+        }
+        if (method === 'ping') {
+            return id === undefined ? null : rpcSuccess(id, {});
+        }
+        if (method === 'tools/list') {
+            if (id === undefined)
+                return null;
+            return rpcSuccess(id, {
+                tools: TOOLS.map((tool) => ({
+                    name: tool.name,
+                    description: tool.description,
+                    inputSchema: tool.inputSchema,
+                })),
+            });
+        }
+        if (method === 'tools/call') {
+            if (id === undefined)
+                return null;
+            const name = request.params?.name;
+            const args = request.params?.arguments ?? {};
+            if (!name) {
+                return rpcError(id, INVALID_PARAMS, 'tools/call requires params.name');
+            }
+            const tool = findTool(name);
+            if (!tool) {
+                return rpcError(id, INVALID_PARAMS, `Unknown tool: ${name}. Available tools: ${TOOLS.map((t) => t.name).join(', ')}.`);
+            }
+            try {
+                const result = await tool.handler(args, deps);
+                return rpcSuccess(id, {
+                    content: [{ type: 'text', text: result.text }],
+                    isError: result.isError ?? false,
+                });
+            }
+            catch (error) {
+                if (error instanceof ToolInputError) {
+                    return rpcError(id, INVALID_PARAMS, error.message);
+                }
+                const message = error instanceof Error ? error.message : String(error);
+                return rpcSuccess(id, {
+                    content: [{ type: 'text', text: `Tool execution failed: ${message}` }],
+                    isError: true,
+                });
+            }
+        }
+        return id === undefined ? null : rpcError(id, METHOD_NOT_FOUND, `Method not found: ${method}`);
+    }
+    return {
+        tools: TOOLS,
+        async handleMessage(line) {
+            let parsed;
+            try {
+                parsed = JSON.parse(line);
+            }
+            catch {
+                return JSON.stringify(rpcError(null, PARSE_ERROR, 'Parse error: invalid JSON'));
+            }
+            if (parsed.jsonrpc !== '2.0' || typeof parsed.method !== 'string') {
+                return JSON.stringify(rpcError(parsed.id ?? null, INVALID_PARAMS, 'Invalid JSON-RPC 2.0 request'));
+            }
+            try {
+                const response = await dispatch(parsed);
+                return response === null ? null : JSON.stringify(response);
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return JSON.stringify(rpcError(parsed.id ?? null, INTERNAL_ERROR, message));
+            }
+        },
+    };
+}

package/dist/stdio.d.ts

@@ -0,0 +1,15 @@
+import type { McpDeps } from './tools.js';
+export interface StdioRunnerOptions {
+    input: NodeJS.ReadableStream;
+    output: NodeJS.WritableStream;
+    deps: McpDeps;
+    onError?: (message: string) => void;
+}
+/**
+ * Newline-delimited JSON-RPC stdio loop. stdout carries ONLY protocol messages;
+ * diagnostics go to the provided error sink (stderr in production).
+ */
+export declare function createStdioRunner(options: StdioRunnerOptions): {
+    stop(): void;
+};
+export declare function createHttpCallApi(apiUrl: string, token: string): McpDeps['callApi'];

package/dist/stdio.js

@@ -0,0 +1,72 @@
+import { createMcpServer } from './server.js';
+/**
+ * Newline-delimited JSON-RPC stdio loop. stdout carries ONLY protocol messages;
+ * diagnostics go to the provided error sink (stderr in production).
+ */
+export function createStdioRunner(options) {
+    const server = createMcpServer(options.deps);
+    const logError = options.onError ?? ((message) => process.stderr.write(`${message}\n`));
+    let buffer = '';
+    let queue = Promise.resolve();
+    const handleLine = (line) => {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            return;
+        queue = queue
+            .then(async () => {
+            const response = await server.handleMessage(trimmed);
+            if (response !== null) {
+                options.output.write(`${response}\n`);
+            }
+        })
+            .catch((error) => {
+            logError(`mcp: internal loop error: ${error instanceof Error ? error.message : String(error)}`);
+        });
+    };
+    const onData = (chunk) => {
+        buffer += chunk.toString();
+        let newlineIndex = buffer.indexOf('\n');
+        while (newlineIndex >= 0) {
+            const line = buffer.slice(0, newlineIndex);
+            buffer = buffer.slice(newlineIndex + 1);
+            handleLine(line);
+            newlineIndex = buffer.indexOf('\n');
+        }
+    };
+    const onEnd = () => {
+        if (buffer.trim().length > 0) {
+            handleLine(buffer);
+            buffer = '';
+        }
+    };
+    options.input.on('data', onData);
+    options.input.on('end', onEnd);
+    return {
+        stop() {
+            options.input.off('data', onData);
+            options.input.off('end', onEnd);
+        },
+    };
+}
+export function createHttpCallApi(apiUrl, token) {
+    const base = apiUrl.replace(/\/+$/, '');
+    return async (method, path, body) => {
+        const res = await fetch(`${base}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${token}`,
+                ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
+            },
+            ...(body !== undefined ? { body: JSON.stringify(body) } : {}),
+        });
+        const text = await res.text();
+        let parsed = null;
+        try {
+            parsed = text.length > 0 ? JSON.parse(text) : null;
+        }
+        catch {
+            parsed = { raw: text.slice(0, 500) };
+        }
+        return { status: res.status, body: parsed };
+    };
+}

package/dist/tools.d.ts

@@ -0,0 +1,32 @@
+/**
+ * MCP tool surface (adapter layer). Handlers validate inputs, delegate to the
+ * MayaMemo HTTP API via `deps.callApi`, and bound their outputs.
+ * V1 tools per docs/MCP.md: context_get, context_search, memory_search,
+ * memory_save, project_state, checkpoint_create (unlocked at M06).
+ */
+/** Thrown by handlers for invalid tool arguments → JSON-RPC -32602. */
+export declare class ToolInputError extends Error {
+}
+export interface McpDeps {
+    callApi: (method: 'GET' | 'POST', path: string, body?: unknown) => Promise<{
+        status: number;
+        body: unknown;
+    }>;
+}
+export interface McpToolResult {
+    text: string;
+    isError?: boolean;
+}
+export interface McpToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    handler: (args: Record<string, unknown>, deps: McpDeps) => Promise<McpToolResult>;
+}
+export declare const CHECKPOINT_TOOL_READY = true;
+export declare const MAX_CONTEXT_ITEMS = 30;
+export declare const MAX_SEARCH_RESULTS = 25;
+export declare const MAX_ITEM_CHARS = 400;
+export declare const TOOLS: McpToolDefinition[];
+export declare function findTool(name: string): McpToolDefinition | undefined;
+export declare const MCP_TOOL_NAMES: string[];

package/dist/tools.js

@@ -0,0 +1,622 @@
+/**
+ * MCP tool surface (adapter layer). Handlers validate inputs, delegate to the
+ * MayaMemo HTTP API via `deps.callApi`, and bound their outputs.
+ * V1 tools per docs/MCP.md: context_get, context_search, memory_search,
+ * memory_save, project_state, checkpoint_create (unlocked at M06).
+ */
+/** Thrown by handlers for invalid tool arguments → JSON-RPC -32602. */
+export class ToolInputError extends Error {
+}
+export const CHECKPOINT_TOOL_READY = true;
+export const MAX_CONTEXT_ITEMS = 30;
+export const MAX_SEARCH_RESULTS = 25;
+export const MAX_ITEM_CHARS = 400;
+function requireString(args, key) {
+    const value = args[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new ToolInputError(`Missing or invalid required argument: ${key}`);
+    }
+    return value;
+}
+function optionalString(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'string')
+        throw new ToolInputError(`Argument ${key} must be a string`);
+    return value;
+}
+function optionalNumber(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== 'number' || Number.isNaN(value)) {
+        throw new ToolInputError(`Argument ${key} must be a number`);
+    }
+    return value;
+}
+function optionalStringArray(args, key, cap) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value) || value.some((v) => typeof v !== 'string')) {
+        throw new ToolInputError(`Argument ${key} must be an array of strings`);
+    }
+    return value.slice(0, cap);
+}
+function entityRefs(args, key, cap) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new ToolInputError(`Argument ${key} must be an array`);
+    const refs = [];
+    for (const item of value.slice(0, cap)) {
+        const record = item;
+        if (typeof record?.kind !== 'string' || typeof record?.name !== 'string') {
+            throw new ToolInputError(`Argument ${key} entries need string "kind" and "name"`);
+        }
+        refs.push({ kind: record.kind, name: record.name });
+    }
+    return refs;
+}
+function apiErrorText(status, body) {
+    const error = body.error;
+    const code = error?.code ?? 'API_ERROR';
+    const message = error?.message ?? `HTTP ${status}`;
+    return { text: `MayaMemo API error (${status}) [${code}]: ${message}`, isError: true };
+}
+function bounded(text, max = MAX_ITEM_CHARS) {
+    return text.length > max ? `${text.slice(0, max)}…` : text;
+}
+export const TOOLS = [
+    {
+        name: 'memory_save',
+        description: 'Save a durable project memory (decision, constraint, bug, lesson, fact, preference, task, discovery, incident, architecture, requirement) to the MayaMemo ledger. Long statements are chunked server-side on sentence boundaries — nothing is dropped.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'MayaMemo project id (from the project mapping)' },
+                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' },
+                importance: { type: 'number', description: '0..1 how valuable for future sessions' },
+                source_session_id: { type: 'string', description: 'Optional source session id' },
+                source_event_id: { type: 'string', description: 'Optional source event id' },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional tags for organization/filtering (lowercased, max 10, alphanumeric)',
+                },
+                entities: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            kind: { type: 'string', description: 'file, module, symbol, endpoint, table, concept…' },
+                            name: { type: 'string' },
+                        },
+                        required: ['kind', 'name'],
+                    },
+                    description: 'Optional code entities this memory is about (linked into the project graph)',
+                },
+            },
+            required: ['project_id', 'statement', 'type'],
+        },
+        async handler(args, deps) {
+            const payload = {
+                project_id: requireString(args, 'project_id'),
+                statement: requireString(args, 'statement'),
+                type: requireString(args, 'type'),
+            };
+            const confidence = optionalNumber(args, 'confidence');
+            if (confidence !== undefined)
+                payload.confidence = confidence;
+            const importance = optionalNumber(args, 'importance');
+            if (importance !== undefined)
+                payload.importance = importance;
+            const sourceSession = optionalString(args, 'source_session_id');
+            if (sourceSession !== undefined)
+                payload.source_session_id = sourceSession;
+            const sourceEvent = optionalString(args, 'source_event_id');
+            if (sourceEvent !== undefined)
+                payload.source_event_id = sourceEvent;
+            if (Array.isArray(args.tags) && args.tags.length > 0)
+                payload.tags = args.tags.map(String);
+            const memoryEntities = entityRefs(args, 'entities', 20);
+            if (memoryEntities)
+                payload.entities = memoryEntities;
+            const res = await deps.callApi('POST', '/v1/memories', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const memory = res.body;
+            return {
+                text: `Saved memory ${memory.id} [${memory.type}/${memory.status}]: ${bounded(memory.statement)}`,
+            };
+        },
+    },
+    {
+        name: 'memory_search',
+        description: 'Hybrid (semantic + keyword) search over the project memory ledger. Supports temporal queries natively — "what changed last week", "since 2026-09-01" — parsed deterministically (no LLM). Returns ranked memories with provenance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string' },
+                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)' },
+                tags: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Optional tag filter — only memories carrying ALL given tags are returned',
+                },
+                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'],
+        },
+        async handler(args, deps) {
+            const payload = {
+                project_id: requireString(args, 'project_id'),
+                query: requireString(args, 'query'),
+            };
+            const status = optionalString(args, 'status');
+            if (status !== undefined)
+                payload.status = status;
+            const limit = optionalNumber(args, 'limit');
+            payload.limit = Math.min(Math.max(limit ?? 8, 1), MAX_SEARCH_RESULTS);
+            if (Array.isArray(args.tags) && args.tags.length > 0)
+                payload.tags = args.tags.map(String);
+            // Q13: explicit temporal bounds pass through; NL phrases ("last week")
+            // are parsed server-side from the query text automatically.
+            const since = optionalString(args, 'since');
+            if (since !== undefined)
+                payload.since = since;
+            const until = optionalString(args, 'until');
+            if (until !== undefined)
+                payload.until = until;
+            const res = await deps.callApi('POST', '/v1/memories/search', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const rows = res.body;
+            if (rows.length === 0)
+                return { text: 'No memories matched.' };
+            const lines = rows
+                .slice(0, MAX_SEARCH_RESULTS)
+                .map((r, i) => `${i + 1}. [${r.type}] ${bounded(r.statement)}${r.score !== undefined ? ` (score ${Number(r.score).toFixed(3)})` : ''}`);
+            return { text: `${rows.length} memories:\n${lines.join('\n')}` };
+        },
+    },
+    {
+        name: 'context_search',
+        description: 'Compile the minimum sufficient context for a task from the project ledger, memories, and sessions. Respects a hard token budget and returns explainable provenance.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string' },
+                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'],
+        },
+        async handler(args, deps) {
+            const payload = {
+                project_id: requireString(args, 'project_id'),
+                title: requireString(args, 'query'),
+                token_budget: Math.min(Math.max(optionalNumber(args, 'token_budget') ?? 4000, 64), 50000),
+                max_items: MAX_CONTEXT_ITEMS,
+            };
+            const branch = optionalString(args, 'branch');
+            if (branch !== undefined)
+                payload.branch = branch;
+            const res = await deps.callApi('POST', '/v1/context/compile', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            const lines = body.items
+                .slice(0, MAX_CONTEXT_ITEMS)
+                .map((item) => {
+                const preview = item.reason?.preview ?? item.source_id;
+                return `${item.rank}. [${item.source_type}] ${bounded(preview)}`;
+            });
+            return {
+                text: [
+                    `Context version ${body.version_id} — ${body.token_count}/${body.token_budget} tokens, ${body.items.length} items (${body.excluded_count} excluded).`,
+                    ...lines,
+                ].join('\n'),
+            };
+        },
+    },
+    {
+        name: 'context_get',
+        description: 'Fetch a previously compiled context version by id, with hydrated item content.',
+        inputSchema: {
+            type: 'object',
+            properties: { version_id: { type: 'string', description: 'Context version id' } },
+            required: ['version_id'],
+        },
+        async handler(args, deps) {
+            const versionId = requireString(args, 'version_id');
+            const res = await deps.callApi('GET', `/v1/context/${encodeURIComponent(versionId)}`);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            const lines = body.items
+                .slice(0, MAX_CONTEXT_ITEMS)
+                .map((item) => `${item.rank}. [${item.source_type}] ${bounded(item.content ?? '')}`);
+            return {
+                text: [
+                    `Context version ${versionId} — ${body.token_count}/${body.token_budget} tokens.`,
+                    ...lines,
+                ].join('\n'),
+            };
+        },
+    },
+    {
+        name: 'project_state',
+        description: 'Project state snapshot: counts, last session, last checkpoint, and recent ledger activity.',
+        inputSchema: {
+            type: 'object',
+            properties: { project_id: { type: 'string' } },
+            required: ['project_id'],
+        },
+        async handler(args, deps) {
+            const projectId = requireString(args, 'project_id');
+            const res = await deps.callApi('GET', `/v1/projects/${encodeURIComponent(projectId)}/state`);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const state = res.body;
+            const lines = [
+                `Project "${state.project.name}": ${state.memories.active} active memories (${state.memories.superseded} superseded), ${state.events_count} ledger events.`,
+                state.last_session
+                    ? `Last session: ${state.last_session.started_at} on ${state.last_session.branch ?? 'unknown branch'}`
+                    : 'No sessions yet.',
+                state.last_checkpoint
+                    ? `Last checkpoint ${state.last_checkpoint.id} (${state.last_checkpoint.created_at}) — take over with checkpoint_resume when you are the next agent.`
+                    : 'No checkpoints yet.',
+                `Recent: ${state.recent_events.map((e) => e.event_type).join(', ')}`,
+            ];
+            return { text: lines.join('\n') };
+        },
+    },
+    {
+        name: 'checkpoint_create',
+        description: 'Create a handoff checkpoint: compiles (or links) context, builds an evidence-backed passport from the ledger, and records it for cross-agent resume.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string' },
+                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' },
+                blockers: { type: 'array', items: { type: 'string' }, description: 'Known blockers (auto-derived if omitted)' },
+                agent: { type: 'string', description: 'Agent key creating the checkpoint, e.g. "opencode"' },
+                session_id: { type: 'string', description: 'Source session id' },
+                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'],
+        },
+        async handler(args, deps) {
+            const payload = {
+                project_id: requireString(args, 'project_id'),
+                title: requireString(args, 'title'),
+                summary: requireString(args, 'summary'),
+            };
+            const nextSteps = optionalStringArray(args, 'next_steps', 20);
+            if (nextSteps !== undefined)
+                payload.next_steps = nextSteps;
+            const blockers = optionalStringArray(args, 'blockers', 20);
+            if (blockers !== undefined)
+                payload.blockers = blockers;
+            const agent = optionalString(args, 'agent');
+            if (agent !== undefined)
+                payload.agent = agent;
+            const sessionId = optionalString(args, 'session_id');
+            if (sessionId !== undefined)
+                payload.session_id = sessionId;
+            const contextVersionId = optionalString(args, 'context_version_id');
+            if (contextVersionId !== undefined)
+                payload.context_version_id = contextVersionId;
+            const tokenBudget = optionalNumber(args, 'token_budget');
+            if (tokenBudget !== undefined)
+                payload.token_budget = Math.min(Math.max(tokenBudget, 64), 50000);
+            const res = await deps.callApi('POST', '/v1/checkpoints', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const checkpoint = res.body;
+            return {
+                text: `Checkpoint ${checkpoint.id} [${checkpoint.status}]: ${bounded(checkpoint.title)} — context ${checkpoint.context_version_id} (${checkpoint.token_count} tokens, ${checkpoint.item_count} items)`,
+            };
+        },
+    },
+    {
+        name: 'entity_observe',
+        description: 'Report code entities (files, modules, symbols, endpoints, tables, concepts) and relations (imports, calls, defines, reads, depends_on…) — builds the project graph that links memories and files across agents. Idempotent.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'MayaMemo project id' },
+                entities: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: { kind: { type: 'string' }, name: { type: 'string' } },
+                        required: ['kind', 'name'],
+                    },
+                    description: 'Entities observed (max 50)',
+                },
+                relations: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            source: { type: 'object', properties: { kind: { type: 'string' }, name: { type: 'string' } }, required: ['kind', 'name'] },
+                            target: { type: 'object', properties: { kind: { type: 'string' }, name: { type: 'string' } }, required: ['kind', 'name'] },
+                            kind: { type: 'string' },
+                            confidence: { type: 'number' },
+                        },
+                        required: ['source', 'target', 'kind'],
+                    },
+                    description: 'Relations between entities (max 100)',
+                },
+            },
+            required: ['project_id'],
+        },
+        async handler(args, deps) {
+            const payload = { project_id: requireString(args, 'project_id') };
+            const entities = entityRefs(args, 'entities', 50);
+            if (entities)
+                payload.entities = entities;
+            const relations = args.relations;
+            if (Array.isArray(relations) && relations.length > 0) {
+                if (relations.length > 100)
+                    throw new ToolInputError('Argument relations exceeds 100 entries');
+                payload.relations = relations;
+            }
+            if (!payload.entities && !payload.relations) {
+                throw new ToolInputError('Provide at least one entity or relation');
+            }
+            const res = await deps.callApi('POST', '/v1/entities/observe', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            return {
+                text: `Graph updated: ${body.entity_count} entities (${body.created_entities} new), ${body.relation_count} relations.`,
+            };
+        },
+    },
+    {
+        name: 'graph_query',
+        description: 'Query the project graph: list/search entities by name or kind, or get the neighbors (depth 1-2) of one entity — files, modules, symbols and how they relate.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'MayaMemo project id (required when listing)' },
+                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' },
+                depth: { type: 'number', description: 'Neighbor depth 1-2 (default 1)' },
+            },
+            required: [],
+        },
+        async handler(args, deps) {
+            const entityId = optionalString(args, 'entity_id');
+            if (entityId) {
+                const depth = Math.min(Math.max(optionalNumber(args, 'depth') ?? 1, 1), 2);
+                const res = await deps.callApi('GET', `/v1/entities/${entityId}/neighbors?depth=${depth}`);
+                if (res.status >= 400)
+                    return apiErrorText(res.status, res.body);
+                const graph = res.body;
+                const lines = graph.nodes
+                    .slice(0, MAX_SEARCH_RESULTS)
+                    .map((n) => `- [d${n.depth}] ${n.kind} ${n.name}`);
+                return {
+                    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 params = new URLSearchParams();
+            const q = optionalString(args, 'q');
+            if (q)
+                params.set('q', q);
+            const kind = optionalString(args, 'kind');
+            if (kind)
+                params.set('kind', kind);
+            params.set('limit', '25');
+            const res = await deps.callApi('GET', `/v1/projects/${projectId}/entities?${params.toString()}`);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            if (body.entities.length === 0)
+                return { text: 'No entities match.' };
+            const lines = body.entities.map((e) => `- ${e.kind} ${e.name} (id ${e.id}, ${e.relationCount} relations, ${e.memoryCount} memories)`);
+            return { text: `${body.entities.length} entities:\n${lines.join('\n')}` };
+        },
+    },
+    {
+        name: 'attachment_upload',
+        description: 'Upload a file or image to the project (base64). Content-addressed: re-uploading identical bytes returns the existing attachment. Optionally link it to a memory.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'MayaMemo project id' },
+                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'],
+        },
+        async handler(args, deps) {
+            const payload = {
+                project_id: requireString(args, 'project_id'),
+                filename: requireString(args, 'filename'),
+                content_base64: requireString(args, 'content_base64'),
+            };
+            const mime = optionalString(args, 'mime');
+            if (mime)
+                payload.mime = mime;
+            const memoryId = optionalString(args, 'memory_id');
+            if (memoryId)
+                payload.memory_id = memoryId;
+            const res = await deps.callApi('POST', '/v1/attachments', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            const linked = body.memoryId ? `, linked to memory ${body.memoryId}` : '';
+            return {
+                text: `${body.deduped ? 'Reused existing' : 'Uploaded'} ${body.kind} attachment ${body.id} (${body.filename}, ${body.sizeBytes} bytes${linked})`,
+            };
+        },
+    },
+    {
+        name: 'attachment_describe',
+        description: 'Describe an image attachment with the configured vision model and (by default) save the description as a durable project memory.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                attachment_id: { type: 'string', description: 'Image attachment id' },
+                prompt: { type: 'string', description: 'Optional custom description prompt' },
+                create_memory: { type: 'boolean', description: 'Set false to return the description without saving a memory' },
+            },
+            required: ['attachment_id'],
+        },
+        async handler(args, deps) {
+            const attachmentId = requireString(args, 'attachment_id');
+            const payload = {};
+            const prompt = optionalString(args, 'prompt');
+            if (prompt)
+                payload.prompt = prompt;
+            if (typeof args.create_memory === 'boolean')
+                payload.create_memory = args.create_memory;
+            const res = await deps.callApi('POST', `/v1/attachments/${encodeURIComponent(attachmentId)}/describe`, payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            const memory = body.memory_id ? `\nSaved memory ${body.memory_id}${body.deduped ? ' (deduped)' : ''}.` : '';
+            return { text: `Description: ${bounded(body.description)}${memory}` };
+        },
+    },
+    {
+        name: 'memory_feedback',
+        description: 'Vote 👍 (up) or 👎 (down) on a memory: did it help the task? Votes are recorded in the ledger and nudge retrieval ranking (up = rank higher, down = rank lower).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                memory_id: { type: 'string', description: 'Memory id' },
+                signal: { type: 'string', description: '"up" or "down"' },
+                reason: { type: 'string', description: 'Optional short reason (audited in the event payload)' },
+            },
+            required: ['memory_id', 'signal'],
+        },
+        async handler(args, deps) {
+            const memoryId = requireString(args, 'memory_id');
+            const signal = requireString(args, 'signal');
+            if (signal !== 'up' && signal !== 'down') {
+                return { text: 'signal must be "up" or "down".', isError: true };
+            }
+            const payload = { signal };
+            const reason = optionalString(args, 'reason');
+            if (reason)
+                payload.reason = reason;
+            const res = await deps.callApi('POST', `/v1/memories/${encodeURIComponent(memoryId)}/feedback`, payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            return {
+                text: `Recorded ${signal === 'up' ? '👍' : '👎'} for memory ${memoryId} (up ${body.feedback_up} / down ${body.feedback_down}, utility ${body.utility}).`,
+            };
+        },
+    },
+    {
+        name: 'session_start',
+        description: 'Start a work session for this project: sessions anchor events, checkpoints and dashboard activity, and make handoff metrics count. Call once when starting a work block and close it with session_end.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: { type: 'string', description: 'MayaMemo project id (from the project mapping)' },
+                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'],
+        },
+        async handler(args, deps) {
+            const payload = { project_id: requireString(args, 'project_id') };
+            const agent = optionalString(args, 'agent');
+            if (agent)
+                payload.agent = agent;
+            const branch = optionalString(args, 'branch');
+            if (branch)
+                payload.branch = branch;
+            const summary = optionalString(args, 'summary');
+            if (summary)
+                payload.summary = summary;
+            const res = await deps.callApi('POST', '/v1/sessions', payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const session = res.body;
+            return {
+                text: `Started session ${session.id}${agent ? ` (agent ${agent})` : ''}. Close it with session_end when the work block is done.`,
+            };
+        },
+    },
+    {
+        name: 'session_end',
+        description: 'Complete a work session started with session_start (optionally leave a summary for the next agent).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: { type: 'string', description: 'Session id returned by session_start' },
+                summary: { type: 'string', description: 'Optional summary of what the session did' },
+            },
+            required: ['session_id'],
+        },
+        async handler(args, deps) {
+            const sessionId = requireString(args, 'session_id');
+            const payload = {};
+            const summary = optionalString(args, 'summary');
+            if (summary)
+                payload.summary = summary;
+            const res = await deps.callApi('POST', `/v1/sessions/${encodeURIComponent(sessionId)}/complete`, payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            return { text: `Completed session ${sessionId}.` };
+        },
+    },
+    {
+        name: 'checkpoint_resume',
+        description: 'Take over from a checkpoint: records the cross-agent handoff (so handoff metrics count it), starts a resume session and returns the full resume briefing. Read the briefing before touching code.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                checkpoint_id: { type: 'string', description: 'Checkpoint id (e.g. from project_state)' },
+                agent: { type: 'string', description: 'Your agent name (recorded as the resuming agent)' },
+                note: { type: 'string', description: 'Optional short note stored with the resume event' },
+            },
+            required: ['checkpoint_id', 'agent'],
+        },
+        async handler(args, deps) {
+            const checkpointId = requireString(args, 'checkpoint_id');
+            const agent = requireString(args, 'agent');
+            const payload = { agent };
+            const note = optionalString(args, 'note');
+            if (note)
+                payload.note = note;
+            const res = await deps.callApi('POST', `/v1/checkpoints/${encodeURIComponent(checkpointId)}/resume`, payload);
+            if (res.status >= 400)
+                return apiErrorText(res.status, res.body);
+            const body = res.body;
+            const sessionLine = body.resumed_session
+                ? `Resumed checkpoint ${checkpointId} as session ${body.resumed_session.id} (agent ${body.resumed_session.agent ?? agent}).`
+                : `Resumed checkpoint ${checkpointId} (agent ${agent}).`;
+            return { text: `${sessionLine}\n\n${body.briefing_markdown ?? '(no briefing returned)'}` };
+        },
+    },
+];
+export function findTool(name) {
+    return TOOLS.find((tool) => tool.name === name);
+}
+export const MCP_TOOL_NAMES = TOOLS.map((tool) => tool.name);

package/package.json

@@ -1,6 +1,36 @@
 {
   "name": "@mayamemo/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MayaMemo MCP server — durable project memory, checkpoints and handoffs for coding agents over stdio.",
+  "license": "MIT",
+  "type": "module",
+  "private": false,
+  "bin": {
+    "mayamemo-mcp": "dist/bin.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Coin1511/mayamemo.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/Coin1511/mayamemo#readme",
+  "keywords": ["mcp", "model-context-protocol", "ai-agents", "coding-agents", "memory", "context", "opencode"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.11"
+  }
+}