@aipoch/open-science 1.0.3 → 1.0.4

package/CLI.md

@@ -849,3 +849,83 @@ older releases. To switch a file credential back to OS storage, restart in OS mo
 replace it with the key while the vault is available. Existing unreadable records remain intact.
 These commands do not migrate historical configuration or store diagnostic history. Older backends that
 lack the endpoints return an endpoint error; the CLI never falls back to editing Settings files directly.
+
+## External agents through MCP
+
+Start the selected profile normally, then let an MCP client launch the stdio adapter:
+
+```bash
+open-science start --no-open --config-root /absolute/path/to/profile
+open-science mcp --config-root /absolute/path/to/profile
+```
+
+Example client configuration (replace paths with your installation and profile paths):
+
+```json
+{
+  "mcpServers": {
+    "open-science": {
+      "command": "/absolute/path/to/open-science",
+      "args": ["mcp", "--config-root", "/absolute/path/to/profile"]
+    }
+  }
+}
+```
+
+`--profile` is an alias for `--config-root`; existing environment overrides and discovery order
+apply. For a source checkout, use `node` as the command and put the absolute path to
+`packages/open-science/cli.mjs` before `mcp` in `args`. The adapter connects to an already
+running authenticated local service; it does not start it, install anything or open a browser.
+`open-science mcp --help` works without a running service.
+
+Tool discovery works even when the service is stopped. Calls return an actionable error until
+it is available, and subsequent calls rediscover the service. Tool names consistently use
+lowercase `snake_case`; argument names retain the SDK's `camelCase`. Tools accept explicit IDs
+rather than resolving project names. Each tool publishes its description, input schema, output
+schema and behavior annotations through `tools/list`.
+
+| Tool                           | Purpose                                                  |
+| ------------------------------ | -------------------------------------------------------- |
+| `doctor`                       | Check research readiness                                 |
+| `list_runtimes`                | List detected Agent runtimes                             |
+| `list_projects`                | List projects and IDs                                    |
+| `create_project`               | Create a persistent project                              |
+| `update_project`               | Update project metadata and Agent Context                |
+| `list_sessions`                | List sessions, optionally by project                     |
+| `get_session`                  | Read session information/status, not a full transcript   |
+| `get_session_configuration`    | Read session configuration and revision                  |
+| `update_session_configuration` | Update settings with `expectedRevision`                  |
+| `start_run`                    | Submit a prompt and return a run ID                      |
+| `get_run`                      | Read progress, output and attention state                |
+| `cancel_run`                   | Explicitly cancel a run without undoing previous effects |
+| `get_plan`                     | Read the plan and its version/revision                   |
+| `respond_plan`                 | Approve/reject a reviewed version or request changes     |
+| `list_artifacts`               | List artifact metadata without downloading files         |
+
+A typical workflow calls `list_projects`, `start_run` with `{ "projectId": "…", "prompt": "…" }`,
+then polls `get_run` with the returned run ID and calls `list_artifacts` with the session ID.
+Successful calls return `structuredContent: { "result": ... }` plus the same JSON in text
+content. Tool execution failures set `isError: true`; exception bodies and credentials are not
+forwarded. After a timeout or transport failure, inspect current state before repeating a write:
+the original operation may already have succeeded. The adapter never retries mutations itself.
+
+Runs use the service's configured framework and authorization defaults. `start_run` accepts
+existing session, provider/model, permission, skill, specialist, compute-host, memory, review,
+delegation and plan-first options; it does not change the global framework. A run can require
+human action in Open-Science. Explicit `permissionPrompts: "none"` denies unresolved human
+interactions using the existing capability check; it does not expand permissions and cannot
+be combined with `turnIntent: "plan-first"`. Plan approval/rejection requires the version and
+revision from `get_plan`. Configuration updates require the revision from
+`get_session_configuration`.
+
+MCP access grants the listed operations for the selected profile under its existing permissions.
+The adapter is not a separate sandbox or a read-only view. Project/configuration changes, plan
+responses and research runs persist through existing business owners and may write files or
+incur model costs. No new database schema, historical-data migration, business status enum,
+credential store or background service is introduced. There is no arbitrary shell/RPC tool,
+credential-management tool, file import/export/download-to-path tool or remote HTTP MCP endpoint.
+
+Standard output carries only MCP protocol messages. Closing stdin or sending SIGINT/SIGTERM
+closes the adapter and its pending network requests; it neither stops the service nor cancels
+accepted runs. MCP request cancellation likewise stops waiting, not the persisted operation.
+Use `cancel_run` explicitly to cancel research.

package/cli.mjs

@@ -40,6 +40,7 @@ Commands:
   stop        Gracefully stop the backend
   status      Show backend status
   url         Print the authenticated web URL
+  mcp         Serve research tools over MCP stdio (--config-root <path> or --profile <path>)
   doctor --json  Inspect headless readiness
   runtime list          List detected Agent runtimes
   runtime install codex   Prepare the app-managed Codex runtime
@@ -203,6 +204,7 @@ const POSITIONAL_LIMITS = new Map([
   ['version', 0],
   ['help', 1],
   ['paths', 0],
+  ['mcp', 0],
   ['doctor', 0],
   ['runtime list', 0],
   ['runtime install', 1],
@@ -282,9 +284,11 @@ export const parseCliArgs = (argv) => {
       ? ['--json', '--help', '-h']
       : command === 'paths'
         ? ['--json', '--help', '-h', '--config-root', '--profile']
-        : command === 'help'
-          ? ['--help', '-h']
-          : undefined
+        : command === 'mcp'
+          ? ['--help', '-h', '--config-root', '--profile']
+          : command === 'help'
+            ? ['--help', '-h']
+            : undefined
   const subcommand =
     (GROUP_COMMANDS.has(command) && args[0] && !args[0].startsWith('-')) ||
     (command === 'run' && (args[0] === 'status' || args[0] === 'cancel'))
@@ -1878,7 +1882,11 @@ export const runCli = async (argv = process.argv.slice(2)) => {
     const { version } = await readCliMetadata()
     console.log(options.json ? JSON.stringify({ version }) : version)
   } else if (command === 'paths') await pathsCommand(options)
-  else if (command === 'init') await initCommand(options)
+  else if (command === 'mcp') {
+    const { runResearchMcpServer } = await import('./mcp.mjs')
+    const { version } = await readCliMetadata()
+    await runResearchMcpServer({ configRoot: options.configRoot, version })
+  } else if (command === 'init') await initCommand(options)
   else if (command === 'start') await startCommand(options)
   else if (command === 'stop') await stopCommand(options)
   else if (command === 'status') await statusCommand(options)

package/mcp.mjs

@@ -0,0 +1,310 @@
+/* eslint-disable @typescript-eslint/explicit-function-return-type */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+import { connectToOpenScience, OpenScienceApiError } from './index.mjs'
+
+const id = (description) => z.string().trim().min(1).describe(description)
+const sessionId = id('Session ID returned by list_sessions or start_run.')
+const projectId = id('Project ID returned by list_projects or create_project.')
+const runId = id('Run ID returned by start_run.')
+const expectedRevision = z
+  .number()
+  .int()
+  .nonnegative()
+  .describe(
+    'Current revision returned by the corresponding read tool. Stale revisions are rejected.'
+  )
+const agentConfiguration = z.strictObject({
+  providerId: id('Configured provider ID.').optional(),
+  model: id('Model identifier; null follows the provider default.').nullable().optional(),
+  reasoningEffort: z.enum(['default', 'low', 'medium', 'high', 'xhigh', 'max']).optional()
+})
+const sessionSettings = {
+  agentConfiguration: agentConfiguration.optional(),
+  permissionProfile: z
+    .enum(['ask', 'auto', 'full'])
+    .describe(
+      'Existing authorization policy. Omit to retain configured defaults; full grants broad execution authority.'
+    )
+    .optional(),
+  autoReviewEnabled: z.boolean().optional(),
+  memoryEnabled: z.boolean().optional(),
+  delegationPolicy: z.enum(['allow', 'deny']).optional()
+}
+const agentContext = z.string().trim().min(1).max(16000)
+const read = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: false
+}
+const write = {
+  readOnlyHint: false,
+  destructiveHint: true,
+  idempotentHint: false,
+  openWorldHint: true
+}
+const result = (value) => ({
+  content: [{ type: 'text', text: JSON.stringify({ result: value ?? null }) }],
+  structuredContent: { result: value ?? null }
+})
+
+// Do not forward raw exception messages: HTTP failures may contain credentials or response bodies.
+const toolError = (error) => {
+  const messages = {
+    daemon_unavailable:
+      'Open-Science is not running. Start it with "open-science start" for the selected profile, then retry.',
+    unsupported_capability:
+      'The service does not support this operation. Update the service before retrying.',
+    project_not_found: 'Project not found. Refresh list_projects.',
+    session_not_found: 'Session not found. Refresh list_sessions.',
+    run_not_found: 'Run not found. Check the ID returned by start_run.',
+    invalid_request: 'Invalid request. Check the tool arguments and service configuration.',
+    request_timeout:
+      'Request timed out. A write may already have succeeded; check its state before retrying.'
+  }
+  const code =
+    error instanceof OpenScienceApiError && Object.hasOwn(messages, error.code)
+      ? error.code
+      : 'request_failed'
+  const status = error instanceof OpenScienceApiError ? error.status : undefined
+  const message =
+    status === 401 || status === 403
+      ? 'Access denied. Check the selected profile and its service credentials.'
+      : status === 409
+        ? 'The operation conflicts with current state. Read the latest state and revision before retrying.'
+        : (messages[code] ??
+          'The operation failed. Check service readiness and request arguments. A write may already have succeeded; inspect its state before retrying.')
+  return {
+    isError: true,
+    content: [{ type: 'text', text: JSON.stringify({ error: { code, message } }) }]
+  }
+}
+
+export const createResearchMcpServer = ({
+  configRoot,
+  version,
+  connect = connectToOpenScience
+}) => {
+  const server = new McpServer({ name: 'open-science', version })
+  const lifetime = new AbortController()
+  const register = (name, description, shape, annotations, invoke) => {
+    server.registerTool(
+      name,
+      {
+        description,
+        inputSchema: z.strictObject(shape),
+        outputSchema: z.object({ result: z.unknown() }),
+        annotations
+      },
+      async (args, extra) => {
+        const signal = AbortSignal.any([lifetime.signal, extra.signal])
+        try {
+          signal.throwIfAborted()
+          // Rediscover per call so service restarts/token rotation recover without retrying writes.
+          const client = await connect({ configRoot, signal })
+          signal.throwIfAborted()
+          return result(await invoke(client, args, { signal }))
+        } catch (error) {
+          return toolError(error)
+        }
+      }
+    )
+  }
+  register(
+    'doctor',
+    'Check whether the running Open-Science service is ready to execute research tasks. Does not start or configure the service.',
+    {},
+    read,
+    (client, _args, options) => client.doctor(options)
+  )
+  register(
+    'list_runtimes',
+    'List detected Agent runtimes and readiness. Does not install runtimes or change the selected framework.',
+    {},
+    read,
+    (client, _args, options) => client.listRuntimes(options)
+  )
+  register(
+    'list_projects',
+    'List projects and their IDs before choosing a research destination.',
+    {},
+    read,
+    (client, _args, options) => client.listProjects(options)
+  )
+  register(
+    'create_project',
+    'Create a persistent research project. Agent Context applies to future work in this project.',
+    {
+      name: id('Project name.'),
+      description: z.string().optional(),
+      agentContext: agentContext.optional()
+    },
+    write,
+    (client, args, options) => client.createProject(args, options)
+  )
+  register(
+    'update_project',
+    'Update a persistent project. Only supplied fields change; null clears Agent Context.',
+    {
+      projectId,
+      name: id('New project name.').optional(),
+      description: z.string().optional(),
+      agentContext: agentContext.nullable().optional()
+    },
+    write,
+    (client, { projectId, ...patch }, options) => client.updateProject(projectId, patch, options)
+  )
+  register(
+    'list_sessions',
+    'List sessions, optionally within one project. Use the returned ID to inspect or continue a session.',
+    {
+      projectId: projectId.optional()
+    },
+    read,
+    (client, args, options) => client.listSessions(args.projectId, options)
+  )
+  register(
+    'get_session',
+    'Read session information and current status. This is not a full conversation transcript.',
+    { sessionId },
+    read,
+    (client, args, options) => client.getSession(args.sessionId, options)
+  )
+  register(
+    'get_session_configuration',
+    'Read current session configuration and revision before changing it.',
+    { sessionId },
+    read,
+    (client, args, options) => client.getSessionConfiguration(args.sessionId, options)
+  )
+  register(
+    'update_session_configuration',
+    'Update persistent session settings using the latest revision. May change model costs and execution permissions; only supplied fields change.',
+    {
+      sessionId,
+      expectedRevision,
+      ...sessionSettings,
+      computeHosts: z
+        .strictObject({
+          enabled: z.array(id('Enabled Compute Host ID.')),
+          selected: z.array(id('Selected Compute Host ID.'))
+        })
+        .optional()
+    },
+    write,
+    (client, { sessionId, ...patch }, options) =>
+      client.updateSessionConfiguration(sessionId, patch, options)
+  )
+  register(
+    'start_run',
+    'Submit research in a project and immediately return a run ID. Omit sessionId to create a session, or provide it to continue that session through its existing active branch. May write files/data and incur model charges. Poll get_run; disconnecting does not cancel the run. Uses configured framework and permissions, without automatically approving human interactions.',
+    {
+      projectId,
+      prompt: id('Research instructions.'),
+      sessionId: sessionId.optional(),
+      cwd: id('Working directory on the Open-Science host.').optional(),
+      ...sessionSettings,
+      skillIds: z.array(id('Skill ID.')).optional(),
+      specialist: id('Specialist ID or exact name for a new session.').optional(),
+      turnIntent: z
+        .literal('plan-first')
+        .describe('Require an approved plan before execution.')
+        .optional(),
+      permissionPrompts: z
+        .literal('none')
+        .describe(
+          'Deny unresolved human interactions instead of waiting; does not expand permissions. Incompatible with plan-first.'
+        )
+        .optional(),
+      computeHostIds: z.array(id('Selected Compute Host ID.')).optional(),
+      enabledComputeHostIds: z.array(id('Enabled Compute Host ID for a new session.')).optional()
+    },
+    write,
+    (client, { projectId, ...request }, options) => {
+      if (request.turnIntent === 'plan-first' && request.permissionPrompts === 'none') {
+        throw new OpenScienceApiError('Incompatible permission and planning options.', {
+          code: 'invalid_request'
+        })
+      }
+      return client.startRun({ project: projectId, ...request }, options)
+    }
+  )
+  register(
+    'get_run',
+    'Read authoritative run status, progress, result and attention state. Poll this after start_run; a waiting run may require human action in Open-Science.',
+    { runId },
+    read,
+    (client, args, options) => client.getRun(args.runId, options)
+  )
+  register(
+    'cancel_run',
+    'Explicitly cancel a research run and wait for service finalization. This does not undo files, data or costs already produced.',
+    { runId },
+    write,
+    (client, args, options) => client.cancelRun(args.runId, options)
+  )
+  register(
+    'get_plan',
+    'Read the current session plan, artifact version and revision, or null when there is no plan.',
+    { sessionId },
+    read,
+    (client, args, options) => client.getSessionPlan(args.sessionId, options)
+  )
+  register(
+    'respond_plan',
+    'Explicitly approve or reject the reviewed plan version, or request revision with feedback. Approval may resume execution and incur costs. Never approve without reviewing get_plan.',
+    {
+      sessionId,
+      response: z.union([
+        z.strictObject({
+          decision: z.enum(['approved', 'rejected']),
+          artifactVersionId: id('Plan artifact version returned by get_plan.'),
+          expectedRevision
+        }),
+        z.strictObject({ feedback: id('Requested changes to the plan.') })
+      ])
+    },
+    write,
+    (client, args, options) => client.respondSessionPlan(args.sessionId, args.response, options)
+  )
+  register(
+    'list_artifacts',
+    'List generated artifact metadata for a session. Does not download files or write local paths.',
+    { sessionId },
+    read,
+    (client, args, options) => client.listArtifacts(args.sessionId, options)
+  )
+
+  const onclose = server.server.onclose
+  server.server.onclose = () => {
+    lifetime.abort()
+    onclose?.()
+  }
+  return server
+}
+
+export const runResearchMcpServer = async (options) => {
+  const server = createResearchMcpServer(options)
+  const transport = new StdioServerTransport()
+  let closing
+  const close = () => {
+    closing ??= server.close().finally(() => {
+      process.stdin.off('end', close)
+      process.off('SIGINT', close)
+      process.off('SIGTERM', close)
+    })
+    return closing
+  }
+  process.stdin.once('end', close)
+  process.once('SIGINT', close)
+  process.once('SIGTERM', close)
+  try {
+    await server.connect(transport)
+    if (process.stdin.readableEnded) await close()
+  } catch (error) {
+    await close()
+    throw error
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aipoch/open-science",
-  "version": "1.0.3",
+  "version": "1.0.4",
   "description": "Node.js SDK and CLI for the Open-Science local daemon",
   "type": "module",
   "exports": {
@@ -37,11 +37,15 @@
   "publishConfig": {
     "access": "public"
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.31.0",
+    "zod": "^4.6.5"
+  },
   "optionalDependencies": {
-    "@aipoch/open-science-darwin-arm64": "1.0.3",
-    "@aipoch/open-science-darwin-x64": "1.0.3",
-    "@aipoch/open-science-linux-x64-gnu": "1.0.3",
-    "@aipoch/open-science-linux-arm64-gnu": "1.0.3",
-    "@aipoch/open-science-win32-x64": "1.0.3"
+    "@aipoch/open-science-darwin-arm64": "1.0.4",
+    "@aipoch/open-science-darwin-x64": "1.0.4",
+    "@aipoch/open-science-linux-x64-gnu": "1.0.4",
+    "@aipoch/open-science-linux-arm64-gnu": "1.0.4",
+    "@aipoch/open-science-win32-x64": "1.0.4"
   }
 }