@octane-xplat/mcp 0.15.0 → 0.16.1

package/dist/server.js

@@ -0,0 +1,324 @@
+import { discovery_exports } from "./discovery.js";
+import { errors_exports } from "./contracts/errors.js";
+import { identity_exports } from "./contracts/identity.js";
+import { status_exports } from "./status.js";
+import { registerDocsTools } from "./docs.js";
+import { evidence_exports } from "./contracts/evidence.js";
+import { policy_exports } from "./contracts/policy.js";
+import { registerRuntimeTools } from "./runtime/tools.js";
+import { registerInspectionTools } from "./inspection/tools.js";
+import "./inspection/service.js";
+import { z } from "zod";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+//#region src/server.ts
+var SERVER_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")).version;
+var INSTRUCTIONS = "MCP server for Octane Xplat apps. Call xplat_project_status first — it reports detected apps, framework versions, guidance, prerequisites, and capabilities. If several apps are detected, ask the developer which to use and bind it with xplat_select_app; never guess. With a dev-mode app running, xplat_dev_actions lists the app-declared action registry and xplat_dev_action_invoke runs one against an exact instance and registry revision. For runtime work, check xplat_capability_matrix then xplat_targets; xplat_launch starts an owned session as a job and xplat_attach binds a session you already run. Results always say what was actually checked; a successful build is not proof of behavior.";
+var respond = (outcome) => ({
+	structuredContent: outcome,
+	isError: outcome.ok === false,
+	content: [{
+		type: "text",
+		text: JSON.stringify(outcome, null, 2)
+	}]
+});
+var ok = (data) => respond({
+	ok: true,
+	data
+});
+var fail = (error) => respond({
+	ok: false,
+	error
+});
+/** The bound app for runtime tools — explicit, configured, or sole-app. */
+var boundApp = (context) => {
+	const selection = (0, status_exports.resolveSelection)(context);
+	return selection.state === "bound" ? selection.app : null;
+};
+var NO_APP = () => (0, errors_exports.contractError)("invalid_selection", "No app is bound.", { recovery: { action: "Bind an app with xplat_select_app first." } });
+function createXplatMcpServer(context) {
+	const server = new McpServer({
+		name: status_exports.SERVER_NAME,
+		version: SERVER_VERSION
+	}, { instructions: INSTRUCTIONS });
+	context.policy.setElicitor(async (scope, reason) => {
+		try {
+			if (!server.server.getClientCapabilities()?.elicitation) return "denied";
+			const answer = await server.server.elicitInput({
+				message: `Octane Xplat MCP requests permission "${scope}": ${reason}`,
+				requestedSchema: {
+					type: "object",
+					properties: { grant: {
+						type: "boolean",
+						description: "Grant this permission for the current task"
+					} },
+					required: ["grant"]
+				}
+			});
+			return answer.action === "accept" && answer.content?.grant === true ? "granted" : "denied";
+		} catch {
+			return "denied";
+		}
+	});
+	if (context.code) for (const platform of identity_exports.PLATFORMS) context.capabilities.register({
+		platform,
+		describe: () => [{
+			capability: "code_search",
+			status: "supported",
+			detail: "Exact search reads the bound app and its installed framework sources directly. An optional local semantic index accelerates intent-style queries and never blocks exact retrieval."
+		}]
+	});
+	server.registerTool("xplat_project_status", {
+		description: "Report detected project identity, framework versions, guidance, docs/code-index status, declared platforms, runtime prerequisites, and the capability summary. Call first; call again after changing workspaces or installing dependencies.",
+		inputSchema: { refresh: z.boolean().optional().describe("Re-scan the workspace instead of using the startup snapshot") }
+	}, async ({ refresh }) => {
+		if (refresh) {
+			context.discovery = (0, discovery_exports.discoverWorkspace)(context.workspaceRoot);
+			const bound = context.boundApp;
+			if (bound) {
+				const still = context.discovery.apps.find((a) => a.id === bound.id);
+				context.boundApp = still ?? null;
+				context.selectionReason = still ? "explicit" : null;
+			}
+		}
+		return ok(await (0, status_exports.buildProjectStatus)(context));
+	});
+	server.registerTool("xplat_select_app", {
+		description: "Bind an explicit app for subsequent work. Required when several apps are detected — the server never picks silently. Pass the app id, relative path, or package name from the status report.",
+		inputSchema: { app: z.string().describe("App id, workspace-relative path, or package name") }
+	}, async ({ app }) => {
+		const result = (0, status_exports.bindApp)(context, app);
+		if (result.error) {
+			if (result.error === "ambiguous_selection") return fail((0, errors_exports.contractError)("ambiguous_selection", `"${app}" matches several apps.`, {
+				recovery: { action: "Ask the developer which app to use, then pass its id." },
+				context: { candidates: result.candidates }
+			}));
+			return fail((0, errors_exports.contractError)("invalid_selection", `No app matches "${app}".`, {
+				recovery: { action: "Pick an id from candidates, or check the workspace root." },
+				context: { candidates: result.candidates }
+			}));
+		}
+		return ok({
+			bound: result.app,
+			reason: "explicit"
+		});
+	});
+	server.registerTool("xplat_capability_matrix", {
+		description: "Per-platform capability matrix: build, launch, logs, UI inspection, screenshot, and interaction are separate capabilities. Unsupported or missing capabilities come with an explanation and a usable alternative when one exists.",
+		inputSchema: { platform: z.enum(identity_exports.PLATFORMS).optional().describe("Limit to one platform") }
+	}, async ({ platform }) => {
+		const status = await (0, status_exports.buildProjectStatus)(context);
+		return ok({ capabilities: platform ? status.capabilities.filter((m) => m.platform === platform) : status.capabilities });
+	});
+	server.registerTool("xplat_permissions", {
+		description: "Report permission grants and their states. Workspace scope and ordinary runtime actions reuse the task authorization; screenshots require an explicit per-task developer grant checked at action time.",
+		inputSchema: { scope: z.enum(policy_exports.PERMISSION_SCOPES).optional() }
+	}, async ({ scope }) => {
+		const grants = context.policy.list();
+		if (!scope) return ok({ grants });
+		const grant = grants.find((g) => g.scope === scope);
+		const check = context.policy.require(scope);
+		return ok({
+			grant,
+			check: check.granted ? { granted: true } : {
+				granted: false,
+				error: check.error
+			}
+		});
+	});
+	server.registerTool("xplat_sessions", {
+		description: "List bound sessions: owned sessions the server started and attached user-owned sessions. Runtime tools bind one app to one target; attached sessions are preserved on end.",
+		inputSchema: {}
+	}, async () => ok({ sessions: context.sessions.list() }));
+	server.registerTool("xplat_job_status", {
+		description: "Bounded status query for a job started by a runtime tool.",
+		inputSchema: { jobId: z.string() }
+	}, async ({ jobId }) => {
+		const job = context.jobs.status(jobId);
+		return job ? ok({ job }) : fail((0, errors_exports.contractError)("not_found", `No job "${jobId}".`, { recovery: { action: "Start a job first; finished history is bounded." } }));
+	});
+	server.registerTool("xplat_job_cancel", {
+		description: "Cooperatively cancel a job. Cancelling signals only that job — it never kills an unrelated app or another user’s process.",
+		inputSchema: { jobId: z.string() }
+	}, async ({ jobId }) => {
+		const job = context.jobs.cancel(jobId);
+		return job ? ok({ job }) : fail((0, errors_exports.contractError)("not_found", `No job "${jobId}".`));
+	});
+	server.registerTool("xplat_session_end", {
+		description: "End a session with ownership-safe cleanup: owned sessions release their resources; attached user-owned sessions are detached and preserved.",
+		inputSchema: { sessionId: z.string() }
+	}, async ({ sessionId }) => {
+		const usable = context.sessions.requireUsable(sessionId);
+		if (!usable.usable && usable.error.code === "not_found") return fail(usable.error);
+		return ok({ result: await context.runtime.endSession(sessionId) });
+	});
+	server.registerTool("xplat_dev_actions", {
+		description: "List the bound app's declared development actions — the live registry announced by a running dev app: stable ids, titles, input/result contracts, effects, availability with reasons, and the registry revision. Never executes an action. An empty registry is reported distinctly from a disconnected app.",
+		inputSchema: {}
+	}, async () => {
+		const app = boundApp(context);
+		return app ? ok(await context.devActions.list(app)) : fail(NO_APP());
+	});
+	server.registerTool("xplat_dev_action_invoke", {
+		description: "Invoke an app-declared development action against a specific app instance and registry revision. Input is validated against the declared contract before anything runs; stale revisions, unavailable actions and saturated queues are rejected up front. Returns a job — poll xplat_job_status, cancel with xplat_job_cancel. Successful setup does not prove app behavior; verify separately.",
+		inputSchema: {
+			appInstanceId: z.string().optional().describe("Target app instance from xplat_dev_actions; required when several instances are live"),
+			actionId: z.string().describe("Stable action id from the registry"),
+			input: z.record(z.string(), z.unknown()).optional().describe("Named inputs matching the declared input contract"),
+			registryRevision: z.number().optional().describe("The revision returned by xplat_dev_actions — stale revisions are rejected"),
+			requestKey: z.string().optional().describe("Idempotence key: a retry with the same key returns the live job instead of re-running")
+		}
+	}, async ({ appInstanceId, actionId, input, registryRevision, requestKey }) => {
+		const app = boundApp(context);
+		if (!app) return fail(NO_APP());
+		const result = await context.devActions.invoke(app, {
+			appInstanceId,
+			actionId,
+			input: input ?? {},
+			registryRevision,
+			requestKey
+		});
+		return result.error ? fail(result.error) : ok(result);
+	});
+	server.registerTool("xplat_dev_action_status", {
+		description: "Status of a development-action invocation: job state, structured result or failure, and disclosed partial effects. Same data as xplat_job_status, restricted to dev-action jobs.",
+		inputSchema: { jobId: z.string() }
+	}, async ({ jobId }) => {
+		const described = context.devActions.describeJob(jobId);
+		if (!described) return fail((0, errors_exports.contractError)("not_found", `No job "${jobId}".`, { recovery: { action: "Invoke an action first; finished history is bounded." } }));
+		if (described.job.kind !== "dev-action") return fail((0, errors_exports.contractError)("invalid_selection", `Job "${jobId}" is a ${described.job.kind} job, not a dev-action invocation.`, { recovery: { action: "Use xplat_job_status for other job kinds." } }));
+		return ok(described);
+	});
+	server.registerTool("xplat_evidence", {
+		description: "List, retain, or delete evidence artifacts. Evidence is session-scoped and deleted when the MCP session ends; retain needs an explicit expiration or manual deletion. Deletion cannot erase an external client transcript.",
+		inputSchema: {
+			op: z.enum([
+				"list",
+				"retain",
+				"delete"
+			]),
+			id: z.string().optional().describe("Evidence record id (required for retain/delete)"),
+			expiresAt: z.string().optional().describe("ISO expiration for retain; omit for manual deletion only"),
+			kind: z.enum(evidence_exports.EVIDENCE_KINDS).optional().describe("Filter for list")
+		}
+	}, async ({ op, id, expiresAt, kind }) => {
+		if (op === "list") return ok({ evidence: context.evidence.list({ kind }) });
+		if (!id) return fail((0, errors_exports.contractError)("invalid_selection", `op "${op}" requires an evidence id.`));
+		if (op === "retain") {
+			const result = context.evidence.retain(id, { expiresAt: expiresAt ?? null });
+			return "error" in result ? fail(result.error) : ok(result);
+		}
+		const result = context.evidence.delete(id);
+		return "error" in result ? fail(result.error) : ok(result);
+	});
+	const boundAppForCode = () => {
+		const selection = (0, status_exports.resolveSelection)(context);
+		if (selection.state === "ambiguous") return {
+			app: null,
+			error: (0, errors_exports.contractError)("ambiguous_selection", "Several apps are detected — code retrieval targets the bound app and its installed packages, never a guessed one.", {
+				recovery: { action: "Ask the developer which app to use, then call xplat_select_app." },
+				context: { candidates: selection.candidates.map((a) => a.id) }
+			})
+		};
+		return { app: selection.state === "bound" ? selection.app : null };
+	};
+	const noCodeProvider = () => fail((0, errors_exports.contractError)("unavailable", "No code-search provider is wired into this server (work item C integration absent).", { recovery: { action: "Use your normal file tools; report the missing provider to the developer." } }));
+	const codeResult = (result) => {
+		if (!result?.status) return ok(result);
+		const code = result.status === "unavailable" ? "unavailable" : "invalid_selection";
+		return fail((0, errors_exports.contractError)(code, result.detail ?? result.reason ?? result.status, { context: {
+			status: result.status,
+			reason: result.reason,
+			corpus: result.corpus,
+			path: result.path
+		} }));
+	};
+	server.registerTool("xplat_code_search", {
+		description: "Search current source. mode=exact (default auto includes it) finds identifiers/tokens by exact match over live files; mode=semantic uses an optional local index that never blocks exact retrieval. Corpora stay labeled: app = the bound app, framework = its installed @octane-xplat packages. Results are leads — open refs with xplat_code_read before citing an API.",
+		inputSchema: {
+			query: z.string().describe("Identifier, phrase, or intent to search for"),
+			mode: z.enum([
+				"auto",
+				"exact",
+				"semantic"
+			]).optional().describe("exact = token search over current files; semantic = local index; auto = both"),
+			corpus: z.enum([
+				"app",
+				"framework",
+				"all"
+			]).optional().describe("Default: all"),
+			platform: z.enum(identity_exports.PLATFORMS).optional().describe("Include shared files plus files marked for this platform"),
+			package: z.string().optional().describe("Limit the framework corpus to one package"),
+			limit: z.number().int().min(1).max(50).optional()
+		}
+	}, async ({ query, mode, corpus, platform, package: pkg, limit }) => {
+		if (!context.code) return noCodeProvider();
+		const check = context.policy.require("workspace");
+		if (!check.granted) return fail(check.error);
+		const { app, error } = boundAppForCode();
+		if (error) return fail(error);
+		try {
+			return codeResult(await context.code.search({
+				app,
+				workspaceKind: context.discovery.workspace.kind,
+				query,
+				mode,
+				corpus,
+				platform,
+				package: pkg,
+				limit
+			}));
+		} catch (value) {
+			return fail((0, errors_exports.toContractError)(value));
+		}
+	});
+	server.registerTool("xplat_code_read", {
+		description: "Read current source by a search ref (xplat-code://…) or explicit corpus + path. Bounded slices return a continuation offset; a file that changed or vanished is reported, never served stale.",
+		inputSchema: {
+			ref: z.string().optional().describe("xplat-code://<corpus>/<key> from a search hit"),
+			corpus: z.enum(["app", "framework"]).optional(),
+			package: z.string().optional().describe("Framework package name for corpus=framework"),
+			path: z.string().optional().describe("Workspace-relative path (app) or path inside the package (framework)"),
+			offset: z.number().int().min(0).optional(),
+			limit: z.number().int().min(1).max(64e3).optional()
+		}
+	}, async ({ ref, corpus, package: pkg, path, offset, limit }) => {
+		if (!context.code) return noCodeProvider();
+		const check = context.policy.require("workspace");
+		if (!check.granted) return fail(check.error);
+		const { app, error } = boundAppForCode();
+		if (error) return fail(error);
+		try {
+			return codeResult(await context.code.read({
+				app,
+				workspaceKind: context.discovery.workspace.kind,
+				ref,
+				corpus,
+				package: pkg,
+				path,
+				offset,
+				limit
+			}));
+		} catch (value) {
+			return fail((0, errors_exports.toContractError)(value));
+		}
+	});
+	registerRuntimeTools(server, context, respond);
+	registerDocsTools(server, context, respond);
+	registerInspectionTools(server, context, respond);
+	return {
+		server,
+		context,
+		/** Ownership-safe teardown: end owned sessions, delete session-scoped evidence. */
+		async shutdown() {
+			return {
+				sessions: await context.runtime.endAll(),
+				evidence: context.evidence.closeSession()
+			};
+		}
+	};
+}
+//#endregion
+export { createXplatMcpServer };

package/dist/status.js

@@ -0,0 +1,8 @@
+import { __exportAll, __reExport } from "./_virtual/_rolldown/runtime.js";
+export * from "@octane-xplat/cli/mcp/status";
+//#region src/status.ts
+var status_exports = /* @__PURE__ */ __exportAll({});
+import * as import__octane_xplat_cli_mcp_status from "@octane-xplat/cli/mcp/status";
+__reExport(status_exports, import__octane_xplat_cli_mcp_status);
+//#endregion
+export { status_exports };

package/dist/xplat-mcp.js

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import { status_exports } from "./status.js";
+import { policy_exports } from "./contracts/policy.js";
+import { createXplatMcpServer } from "./server.js";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createCodeService } from "@octane-xplat/cli/mcp/code-service";
+//#region src/xplat-mcp.ts
+var usage = `xplat-mcp — Octane Xplat MCP server (stdio)
+
+Usage: xplat-mcp [--workspace <path>] [--app <id|path|name>]
+                 [--permissions <scope,scope>] [--evidence-dir <path>]
+
+Options may also come from the environment:
+  XPLAT_MCP_WORKSPACE, XPLAT_MCP_APP, XPLAT_MCP_PERMISSIONS, XPLAT_MCP_EVIDENCE_DIR
+
+Scopes: ${policy_exports.PERMISSION_SCOPES.join(", ")}
+Workspace reads and ordinary runtime actions reuse the developer's task
+authorization; visual-capture always needs an explicit per-task grant.
+`;
+var arg = (name) => {
+	const index = process.argv.indexOf(`--${name}`);
+	return index >= 0 ? process.argv[index + 1] : void 0;
+};
+if (process.argv.includes("--help") || process.argv.includes("-h")) {
+	process.stderr.write(usage);
+	process.exit(0);
+}
+var permissionScopes = (arg("permissions") ?? process.env.XPLAT_MCP_PERMISSIONS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+var unknown = permissionScopes.filter((s) => !policy_exports.PERMISSION_SCOPES.includes(s));
+if (unknown.length) process.stderr.write(`xplat-mcp: ignoring unknown permission scopes: ${unknown.join(", ")}\n`);
+var workspaceRoot = arg("workspace") ?? process.env.XPLAT_MCP_WORKSPACE ?? process.cwd();
+var manifest = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8"));
+var context = (0, status_exports.createWorkspaceContext)({
+	workspaceRoot,
+	serverIdentity: {
+		name: "@octane-xplat/mcp",
+		version: manifest.version
+	},
+	appSelector: arg("app") ?? process.env.XPLAT_MCP_APP,
+	permissionScopes: permissionScopes.filter((s) => policy_exports.PERMISSION_SCOPES.includes(s)),
+	evidenceRoot: arg("evidence-dir") ?? process.env.XPLAT_MCP_EVIDENCE_DIR,
+	code: createCodeService({
+		workspaceRoot,
+		workspaceKind: () => context.discovery.workspace.kind
+	})
+});
+var { server, shutdown } = createXplatMcpServer(context);
+var closing = false;
+var close = async () => {
+	if (closing) return;
+	closing = true;
+	try {
+		await shutdown();
+	} catch (error) {
+		const detail = error instanceof Error ? error.message : String(error);
+		process.stderr.write(`xplat-mcp: shutdown cleanup failed: ${detail}\n`);
+	} finally {
+		await server.close();
+		process.exit(0);
+	}
+};
+process.on("SIGINT", close);
+process.on("SIGTERM", close);
+await server.connect(new StdioServerTransport());
+//#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@octane-xplat/mcp",
-  "version": "0.15.0",
+  "version": "0.16.1",
   "description": "MCP server for Octane Xplat consumer apps — project identity, capability discovery, permission and evidence contracts.",
   "license": "MIT",
   "repository": {
@@ -9,39 +9,45 @@
     "directory": "packages/mcp"
   },
   "bin": {
-    "xplat-mcp": "./src/xplat-mcp.mjs"
+    "xplat-mcp": "./dist/xplat-mcp.js"
   },
   "files": [
     "src",
+    "types",
+    "dist",
     "README.md"
   ],
   "type": "module",
   "exports": {
     "./contracts": {
-      "types": "./src/contracts/index.d.ts",
-      "default": "./src/contracts/index.mjs"
+      "types": "./types/contracts/index.d.ts",
+      "default": "./dist/contracts/index.js"
     },
     "./contracts/*": {
-      "types": "./src/contracts/*.d.ts",
-      "default": "./src/contracts/*.mjs"
-    }
+      "types": "./types/contracts/*.d.ts",
+      "default": "./dist/contracts/*.js"
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.31.0",
-    "@octane-xplat/cli": "0.15.0",
+    "@octane-xplat/cli": "0.16.1",
     "yaml": "2.9.1",
     "zod": "4.6.5"
   },
   "devDependencies": {
-    "typescript": "5.9.3"
+    "@types/node": "24.10.1",
+    "typescript": "5.9.3",
+    "vite": "8.3.0"
   },
   "scripts": {
-    "start": "node src/xplat-mcp.mjs",
-    "test": "node --test tests/*.test.mjs",
-    "test:consumer": "node tests/consumer-workflow.mjs",
+    "start": "node src/xplat-mcp.ts",
+    "build": "vite build",
+    "test": "pnpm build && node --test tests/*.test.mjs",
+    "test:consumer": "pnpm build && node tests/consumer-workflow.mjs",
     "typecheck": "tsc -p tsconfig.json"
   }
 }

package/src/context.ts

@@ -0,0 +1,108 @@
+// Shared internal types for the MCP transport adapter. The context object is
+// assembled by createWorkspaceContext in the shared service layer
+// (@octane-xplat/cli/mcp/status); its registries/stores are typed by the
+// published contracts while service slots (runtime, docs, inspection,
+// dev-actions) keep the adapter-facing surface the tools actually use.
+
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js'
+import type { discoverWorkspace } from '@octane-xplat/cli/mcp/discovery'
+import type { CapabilityRegistry } from '../types/contracts/capabilities'
+import type { CodeProvider } from '../types/contracts/code'
+import type { ToolOutcome } from '../types/contracts/errors'
+import type { EvidenceStore } from '../types/contracts/evidence'
+import type { AppRef, Platform } from '../types/contracts/identity'
+import type { PolicyStore } from '../types/contracts/policy'
+import type { Job, JobRegistry, SessionRegistry } from '../types/contracts/sessions'
+import type { ServerInfo } from '../types/contracts/status'
+
+export type Discovery = ReturnType<typeof discoverWorkspace>
+
+/** The app-binding result: explicit/configured binding, sole app, or a list the developer must choose from. */
+export type Selection =
+	| { state: 'bound'; app: AppRef; reason: string | null }
+	| { state: 'ambiguous'; candidates: AppRef[] }
+	| { state: 'none'; reason: string }
+
+export type SelectionReason = 'explicit' | 'configured' | 'sole-app' | null
+
+export interface RuntimeService {
+	registerCapabilities(): void
+	listTargets(args: { platform?: Platform }): Promise<any>
+	build(args: { platform: Platform; requestKey?: string }): Promise<any>
+	launch(args: {
+		platform: Platform
+		targetId?: string
+		requestKey?: string
+		browserMode?: 'headless' | 'headed'
+	}): Promise<any>
+	attach(args: { platform: Platform; targetId?: string }): Promise<any>
+	readLogs(args: {
+		sessionId?: string
+		jobId?: string
+		cursor?: number
+		limit?: number
+		stream?: 'stdout' | 'stderr' | 'lifecycle'
+	}): any
+	endSession(sessionId: string): Promise<any>
+	endAll(): Promise<any>
+}
+
+export interface DocsProvider {
+	status(app: AppRef | null): unknown
+	serviceFor(app: AppRef): {
+		search(args: any): Promise<any>
+		read(args: any): Promise<any>
+		guidance(args: any): Promise<any>
+	}
+}
+
+export interface InspectionService {
+	inspect(args: any): Promise<any>
+	interact(args: any): Promise<any>
+	screenshot(args: any): Promise<any>
+}
+
+export interface DevActionsService {
+	list(app: AppRef): Promise<any>
+	invoke(
+		app: AppRef,
+		args: {
+			appInstanceId?: string
+			actionId: string
+			input: Record<string, unknown>
+			registryRevision?: number
+			requestKey?: string
+		},
+	): Promise<any>
+	describeJob(jobId: string): { job: Job; [key: string]: unknown } | null
+}
+
+export interface WorkspaceContext {
+	workspaceRoot: string
+	configuredAppSelector: string | null
+	serverIdentity: ServerInfo
+	discovery: Discovery
+	boundApp: AppRef | null
+	selectionReason: SelectionReason
+	capabilities: CapabilityRegistry
+	policy: PolicyStore
+	sessions: SessionRegistry
+	jobs: JobRegistry
+	evidence: EvidenceStore
+	docsStatus: (app: AppRef | null) => unknown
+	codeIndexStatus: (app: AppRef | null) => unknown
+	code: CodeProvider | null
+	docs: DocsProvider
+	devActions: DevActionsService
+	runtime: RuntimeService
+	inspection: InspectionService
+}
+
+/** The structuredContent envelope every tool result shares. */
+export interface ToolResponse extends CallToolResult {
+	structuredContent: ToolOutcome<unknown>
+	isError: boolean
+	content: [{ type: 'text'; text: string }]
+}
+
+export type Respond = (outcome: ToolOutcome<unknown>) => ToolResponse

package/src/{docs.mjs → docs.ts}

@@ -2,35 +2,40 @@
 // shared service layer at @octane-xplat/cli/mcp/docs-provider — the CLI's
 // `docs`/`guidance` commands project the same service.
 import { z } from 'zod'
-import { contractError, toContractError } from './contracts/errors.mjs'
-import { PLATFORMS } from './contracts/identity.mjs'
-import { resolveSelection } from './status.mjs'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { contractError, toContractError } from './contracts/errors.ts'
+import { PLATFORMS } from './contracts/identity.ts'
+import { resolveSelection } from './status.ts'
+import type { Respond, Selection, WorkspaceContext } from './context.ts'
+import type { Platform } from '../types/contracts/identity'
 
-export function registerDocsTools(server, context, respond) {
-	const run = (method) => async (args) => {
-		const permission = context.policy.require('workspace')
-		if (!permission.granted) {
-			return respond({ ok: false, error: permission.error })
-		}
+export function registerDocsTools(server: McpServer, context: WorkspaceContext, respond: Respond) {
+	const run =
+		(method: 'search' | 'read' | 'guidance') =>
+		async (args: any): Promise<ReturnType<Respond>> => {
+			const permission = context.policy.require('workspace')
+			if (!permission.granted) {
+				return respond({ ok: false, error: permission.error })
+			}
 
-		const selection = resolveSelection(context)
-		if (selection.state !== 'bound') {
-			return respond({
-				ok: false,
-				error: contractError(
-					selection.state === 'ambiguous' ? 'ambiguous_selection' : 'invalid_selection',
-					'Bind an app with xplat_select_app before retrieving docs.',
-				),
-			})
-		}
+			const selection = resolveSelection(context) as Selection
+			if (selection.state !== 'bound') {
+				return respond({
+					ok: false,
+					error: contractError(
+						selection.state === 'ambiguous' ? 'ambiguous_selection' : 'invalid_selection',
+						'Bind an app with xplat_select_app before retrieving docs.',
+					),
+				})
+			}
 
-		try {
-			const data = await context.docs.serviceFor(selection.app)[method](args)
-			return respond({ ok: true, data })
-		} catch (error) {
-			return respond({ ok: false, error: toContractError(error) })
+			try {
+				const data = await context.docs.serviceFor(selection.app)[method](args)
+				return respond({ ok: true, data })
+			} catch (error) {
+				return respond({ ok: false, error: toContractError(error) })
+			}
 		}
-	}
 
 	server.registerTool(
 		'xplat_docs_search',
@@ -44,7 +49,7 @@ export function registerDocsTools(server, context, respond) {
 					.string()
 					.optional()
 					.describe('Explicit comparison version, visibly outside the installed binding.'),
-				platform: z.enum(PLATFORMS).optional(),
+				platform: z.enum(PLATFORMS as Platform[]).optional(),
 				corpus: z
 					.enum(['guide', 'recipe', 'design-note', 'implementation-note'])
 					.optional()

package/src/inspection/{service.mjs → service.ts}

@@ -2,4 +2,4 @@
 // layer); the MCP tool registration lives in ./tools.mjs. Both names are
 // re-exported here so existing importers keep working.
 export { createInspectionService } from '@octane-xplat/cli/mcp/inspection/service'
-export { registerInspectionTools } from './tools.mjs'
+export { registerInspectionTools } from './tools.ts'