@octane-xplat/mcp 0.1.0 → 0.16.0

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/contracts/actions.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/actions'

package/src/contracts/boundaries.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/boundaries'

package/src/contracts/capabilities.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/capabilities'

package/src/contracts/code.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/code'

package/src/contracts/errors.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/errors'

package/src/contracts/evidence.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/evidence'

package/src/contracts/identity.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/identity'

package/src/contracts/index.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/index'

package/src/contracts/inspection.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/inspection'

package/src/contracts/policy.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/policy'

package/src/contracts/sessions.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/sessions'

package/src/contracts/status.ts

@@ -0,0 +1,3 @@
+// Runtime contract moved to @octane-xplat/cli (shared agent service layer).
+// This shim preserves the @octane-xplat/mcp ./contracts export surface.
+export * from '@octane-xplat/cli/mcp/contracts/status'

package/src/discovery.ts

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/discovery'

package/src/docs.ts

@@ -0,0 +1,89 @@
+// Docs tool registration (MCP adapter). The provider itself lives in the
+// 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 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: 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) 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) })
+			}
+		}
+
+	server.registerTool(
+		'xplat_docs_search',
+		{
+			description:
+				'Search the selected app’s installed-version docs. Results include version/snapshot provenance, unavailable packages, conflicts, and separately labeled project guidance.',
+			inputSchema: {
+				query: z.string().trim().min(1).max(500),
+				package: z.string().optional(),
+				version: z
+					.string()
+					.optional()
+					.describe('Explicit comparison version, visibly outside the installed binding.'),
+				platform: z.enum(PLATFORMS as Platform[]).optional(),
+				corpus: z
+					.enum(['guide', 'recipe', 'design-note', 'implementation-note'])
+					.optional()
+					.default('guide'),
+				limit: z.number().int().min(1).max(50).optional(),
+			},
+		},
+		run('search'),
+	)
+
+	server.registerTool(
+		'xplat_docs_read',
+		{
+			description:
+				'Read a bounded documentation page from a search ref, or package and path, preserving its version binding.',
+			inputSchema: {
+				ref: z.string().optional(),
+				package: z.string().optional(),
+				path: z.string().optional(),
+				version: z.string().optional(),
+				offset: z.number().int().min(0).optional(),
+				limit: z.number().int().min(1).max(20000).optional(),
+			},
+		},
+		run('read'),
+	)
+
+	server.registerTool(
+		'xplat_guidance',
+		{
+			description:
+				'Retrieve tailored guidance for the selected app’s actual installed package versions.',
+			inputSchema: {},
+		},
+		run('guidance'),
+	)
+}

package/src/inspection/service.ts

@@ -0,0 +1,5 @@
+// The inspection service moved to @octane-xplat/cli (shared agent service
+// 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.ts'

package/src/inspection/tools.ts

@@ -0,0 +1,61 @@
+// Inspection tool registration (MCP adapter). The service lives in the
+// shared layer at @octane-xplat/cli/mcp/inspection/service; this file only
+// binds it to MCP tools.
+import { z } from 'zod'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { Respond, WorkspaceContext } from '../context.ts'
+
+export function registerInspectionTools(
+	server: McpServer,
+	context: WorkspaceContext,
+	respond: Respond,
+) {
+	const control = z.object({ kind: z.enum(['id', 'testID']), name: z.string().min(1).max(200) })
+	const run =
+		(method: 'inspect' | 'interact' | 'screenshot') =>
+		async (args: any): Promise<ReturnType<Respond>> => {
+			const data = await context.inspection[method](args)
+			return data.error ? respond({ ok: false, error: data.error }) : respond({ ok: true, data })
+		}
+
+	server.registerTool(
+		'xplat_inspect',
+		{
+			description:
+				'Bounded main-document named DOM hosts in the owned Chromium session. Explicit id/testID selector; duplicates fail. Password/private values are redacted. Includes document/session/build identity and coverage.',
+			inputSchema: {
+				sessionId: z.string(),
+				control: control.optional(),
+				offset: z.number().int().min(0).optional(),
+				limit: z.number().int().min(1).max(100).optional(),
+			},
+		},
+		run('inspect'),
+	)
+
+	server.registerTool(
+		'xplat_interact',
+		{
+			description:
+				'Send scoped input to one stable control from an inspected document. dom-event sends a CDP mouse click; os-input sends Space/Enter via the macOS event system to owned headed Chromium. Reserve desktop input for OS actions. Input delivery is not an app assertion.',
+			inputSchema: {
+				sessionId: z.string(),
+				documentId: z.string(),
+				control,
+				mechanism: z.enum(['dom-event', 'os-input']),
+				key: z.enum(['Space', 'Enter']).optional().default('Space'),
+			},
+		},
+		run('interact'),
+	)
+
+	server.registerTool(
+		'xplat_screenshot',
+		{
+			description:
+				'Capture the owned Chromium viewport only with a current visual-capture grant. Returns a session-scoped artifact and provenance; capability discovery never grants approval.',
+			inputSchema: { sessionId: z.string() },
+		},
+		run('screenshot'),
+	)
+}

package/src/runtime/logs.ts

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/logs'

package/src/runtime/process.ts

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/process'

package/src/runtime/service.ts

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/service'

package/src/runtime/targets.ts

@@ -0,0 +1,2 @@
+// Moved to @octane-xplat/cli (shared agent service layer); re-exported for compatibility.
+export * from '@octane-xplat/cli/mcp/runtime/targets'

package/src/runtime/tools.ts

@@ -0,0 +1,136 @@
+// Runtime MCP tools (work item D). Thin bindings over the runtime service —
+// all session/job/ownership behavior lives in service.mjs and the shared
+// contracts.
+
+import { z } from 'zod'
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { PLATFORMS } from '../contracts/identity.ts'
+import type { Respond, WorkspaceContext } from '../context.ts'
+import type { Platform } from '../../types/contracts/identity'
+
+export function registerRuntimeTools(
+	server: McpServer,
+	context: WorkspaceContext,
+	respond: Respond,
+) {
+	const runtime = context.runtime
+
+	server.registerTool(
+		'xplat_targets',
+		{
+			description:
+				'Discover launchable targets for the bound app: simulators, emulators, devices and host targets with availability, missing-toolchain reasons, and session busy/ownership state.',
+			inputSchema: {
+				platform: z
+					.enum(PLATFORMS as Platform[])
+					.optional()
+					.describe('Limit to one platform'),
+			},
+		},
+		async ({ platform }) => {
+			const result = await runtime.listTargets({ platform })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	server.registerTool(
+		'xplat_build',
+		{
+			description:
+				'Build the bound app for one platform as a background job (the same commands `xplat build` runs). Returns a job id — poll xplat_job_status and read output with xplat_logs. Repeating with the same requestKey returns the live job instead of duplicating it.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS as Platform[]),
+				requestKey: z.string().optional().describe('Idempotence key for retries'),
+			},
+		},
+		async ({ platform, requestKey }) => {
+			const result = await runtime.build({ platform, requestKey })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	server.registerTool(
+		'xplat_launch',
+		{
+			description:
+				'Start an owned development session: bind one app to one target and run the platform dev command as a job. The job completes when readiness is confirmed — a failed launch after a successful build reports accurately, and the session keeps the app alive until xplat_session_end.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS as Platform[]),
+				targetId: z
+					.string()
+					.optional()
+					.describe('Target from xplat_targets; required when several are available'),
+				requestKey: z.string().optional().describe('Idempotence key for retries'),
+				browserMode: z
+					.enum(['headless', 'headed'])
+					.optional()
+					.describe(
+						'Web only. Headed mode enables scoped OS keyboard input on qualified hosts; reserve desktop input before using it.',
+					),
+			},
+		},
+		async ({ platform, targetId, requestKey, browserMode }) => {
+			const result = await runtime.launch({ platform, targetId, requestKey, browserMode })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	server.registerTool(
+		'xplat_attach',
+		{
+			description:
+				'Attach to a compatible development session that is already running — never restarts or terminates it. Reports candidates per platform; attach binds a preserved user-owned session.',
+			inputSchema: {
+				platform: z.enum(PLATFORMS as Platform[]),
+				targetId: z
+					.string()
+					.optional()
+					.describe('Candidate target; required when several are attachable'),
+			},
+		},
+		async ({ platform, targetId }) => {
+			const result = await runtime.attach({ platform, targetId })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+
+	server.registerTool(
+		'xplat_logs',
+		{
+			description:
+				'Bounded, ordered log read for a session or build job. Cursor-paginated: pass the previous nextCursor to continue; truncated/dropped flags reveal gaps and reset marks a restarted capture. A stopped or disconnected session reports its capture as historical.',
+			inputSchema: {
+				sessionId: z.string().optional(),
+				jobId: z.string().optional(),
+				cursor: z.number().optional().describe('Continue after this record seq'),
+				limit: z.number().int().positive().max(5000).optional(),
+				stream: z.enum(['stdout', 'stderr', 'lifecycle']).optional(),
+			},
+		},
+		async ({ sessionId, jobId, cursor, limit, stream }) => {
+			if (!sessionId && !jobId) {
+				return respond({
+					ok: false,
+					error: {
+						code: 'invalid_selection',
+						message: 'Pass a sessionId or a jobId.',
+						recovery: { action: 'Use xplat_sessions or a build/launch job id.' },
+					},
+				})
+			}
+
+			const result = runtime.readLogs({ sessionId, jobId, cursor, limit, stream })
+			return result.error
+				? respond({ ok: false, error: result.error })
+				: respond({ ok: true, data: result })
+		},
+	)
+}