@phyzess/pappra 0.1.0-beta.12 → 0.1.0-beta.13

package/dist/knowledge/scan.js

@@ -0,0 +1,91 @@
+import { discoverWorkspace } from '../workspace/discover.js';
+import { KnowledgeService } from './index.js';
+export function classifyScannedDocumentKind(path) {
+    const lower = path.toLowerCase();
+    if (lower.endsWith('agents.md') || lower.endsWith('claude.md'))
+        return 'rule';
+    if (lower.includes('/research/'))
+        return 'research';
+    if (lower.includes('/adr/') || lower.includes('decision'))
+        return 'decision';
+    if (lower.includes('review') || lower.includes('retro'))
+        return 'review';
+    if (lower.includes('plan'))
+        return 'plan';
+    return 'architecture';
+}
+/**
+ * Registers documents discovered under the configured knowledge sources.
+ * Without apply this is read-only and reports the candidates.
+ */
+export async function scanDiscoveredDocuments(root, options) {
+    const discovery = await discoverWorkspace(root);
+    const config = discovery.config;
+    if (config === null) {
+        return {
+            ok: false,
+            message: 'docs scan requires a valid .pappra/workspace.json; run pappra init first.',
+        };
+    }
+    const service = new KnowledgeService(root);
+    const listed = await service.list({ includePrivate: true });
+    const registered = new Set(listed.records.flatMap((record) => record.location.kind === 'workspace' ? [record.location.path] : []));
+    const sources = config.knowledge.sources;
+    const visibility = config.knowledge.taskVisibility === 'shared' ? 'shareable' : 'private';
+    const candidates = [];
+    for (const document of discovery.documents ?? []) {
+        const path = document.workspaceRelativePath;
+        if (path === null)
+            continue;
+        if (!sources.some((source) => path === source || path.startsWith(`${source}/`))) {
+            continue;
+        }
+        if (registered.has(path))
+            continue;
+        candidates.push({
+            path,
+            kind: classifyScannedDocumentKind(path),
+            visibility,
+        });
+    }
+    const diagnostics = [...listed.diagnostics];
+    if (!options.apply) {
+        return {
+            ok: true,
+            schema: 'pappra/docs-scan/1',
+            mode: 'plan',
+            workspaceRoot: root,
+            candidates,
+            registered: [],
+            skipped: candidates.length,
+            nextActions: [
+                'Rerun with apply: true to register these documents in the knowledge catalog.',
+            ],
+            diagnostics,
+        };
+    }
+    const registeredNow = [];
+    for (const candidate of candidates) {
+        const result = await service.register({
+            location: { kind: 'workspace', path: candidate.path },
+            kind: candidate.kind,
+            maturity: 'draft',
+            owner: 'human',
+            visibility: candidate.visibility,
+        });
+        diagnostics.push(...result.diagnostics);
+        if (result.ok)
+            registeredNow.push(result.record);
+    }
+    return {
+        ok: diagnostics.every((entry) => entry.severity !== 'error'),
+        schema: 'pappra/docs-scan/1',
+        mode: 'apply',
+        workspaceRoot: root,
+        candidates,
+        registered: registeredNow,
+        skipped: candidates.length - registeredNow.length,
+        nextActions: [],
+        diagnostics,
+    };
+}

package/dist/mcp/server.d.ts

@@ -0,0 +1,11 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const MCP_SERVER_NAME = "pappra";
+export interface PappraMcpServerOptions {
+    readonly root: string;
+}
+/**
+ * Builds the stdio MCP server for one workspace. Tools are read-only here; write
+ * operations are added separately and must stay behind apply/confirm gates.
+ */
+export declare function createPappraMcpServer(options: PappraMcpServerOptions): McpServer;
+export declare function runMcpServer(root: string): Promise<void>;

package/dist/mcp/server.js

@@ -0,0 +1,518 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { discoverWorkspace } from '../workspace/discover.js';
+import { inspectMachineConfig, inspectWorkspaceConfig, } from '../workspace/config.js';
+import { inspectRuntimeStatePassive } from '../install/runtime.js';
+import { CheckpointService } from '../continuity/service.js';
+import { KnowledgeService } from '../knowledge/index.js';
+import { CodeIntelligenceService } from '../code/index.js';
+import { HOST_SUPPORT } from '../hosts/integration/support.js';
+import { getPackageInfo } from '../package-info.js';
+import { scanDiscoveredDocuments } from '../knowledge/scan.js';
+import { installRuntime } from '../install/runtime.js';
+import { bindAndRecordRuntime, ensureDefaultRuntime } from '../app/init.js';
+import { prepareFromObjective } from '../app/collab-from.js';
+import { FixtureController, PiRpcController, finishStarted, startPrepared, submitResultReport, } from '../app/collaboration.js';
+export const MCP_SERVER_NAME = 'pappra';
+function toolResult(value, isError = false) {
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${JSON.stringify(value)}\n`,
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+async function errorResult(action) {
+    try {
+        return toolResult(await action());
+    }
+    catch (error) {
+        return toolResult({
+            ok: false,
+            message: error instanceof Error ? error.message : String(error),
+        }, true);
+    }
+}
+/**
+ * Builds the stdio MCP server for one workspace. Tools are read-only here; write
+ * operations are added separately and must stay behind apply/confirm gates.
+ */
+export function createPappraMcpServer(options) {
+    const root = options.root;
+    const server = new McpServer({
+        name: MCP_SERVER_NAME,
+        version: getPackageInfo().version,
+    });
+    server.registerTool('workspace_status', {
+        title: 'Workspace status',
+        description: 'Read-only summary of the workspace configuration, repositories, knowledge sources, hosts and passive runtime state.',
+        annotations: { readOnlyHint: true },
+    }, async () => errorResult(async () => {
+        const workspace = await inspectWorkspaceConfig(root, {
+            missing: 'info',
+        });
+        const machine = await inspectMachineConfig(root);
+        const discovery = await discoverWorkspace(root);
+        const config = workspace.value;
+        const runtime = machine.value?.runtime === null ||
+            machine.value?.runtime === undefined
+            ? null
+            : await inspectRuntimeStatePassive(machine.value.runtime.version);
+        return {
+            ok: workspace.exists && machine.exists,
+            workspaceRoot: root,
+            config: config === null
+                ? null
+                : {
+                    name: config.name,
+                    repositories: config.repositories.map((repository) => ({
+                        id: repository.id,
+                        path: repository.path,
+                        access: repository.access,
+                    })),
+                    knowledgeSources: config.knowledge.sources,
+                    code: config.code,
+                    validation: config.validation.map((entry) => entry.id),
+                    excludes: config.excludes,
+                },
+            hosts: {
+                selected: machine.value?.selectedHosts ?? [],
+                pinned: Object.fromEntries(['pi', 'codex', 'claude'].map((host) => [
+                    host,
+                    HOST_SUPPORT[host].version,
+                ])),
+            },
+            discoveredRepositories: discovery.repositories.length,
+            discoveredDocuments: discovery.documents.length,
+            runtime: runtime === null
+                ? null
+                : {
+                    version: runtime.version,
+                    status: runtime.status,
+                    executableExists: runtime.executableExists,
+                },
+            diagnostics: [
+                ...workspace.diagnostics,
+                ...machine.diagnostics,
+                ...discovery.diagnostics,
+            ].filter((entry) => entry.severity !== 'info'),
+        };
+    }));
+    server.registerTool('resume', {
+        title: 'Resume a task checkpoint',
+        description: 'Reads the stored checkpoint for a task and returns the advisory resume packet. A packet never grants execution.',
+        inputSchema: {
+            task: z.string().min(1).max(256),
+            session: z.string().min(1).max(256).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => errorResult(async () => {
+        const service = new CheckpointService(root);
+        const result = await service.resume({
+            taskId: args.task,
+            ...(args.session === undefined
+                ? {}
+                : { currentSession: args.session }),
+        });
+        return {
+            ok: result.ok,
+            status: result.status,
+            packet: result.packet,
+            diagnostics: result.diagnostics,
+        };
+    }));
+    server.registerTool('docs_list', {
+        title: 'List knowledge documents',
+        description: 'Lists registered knowledge documents. Private documents require includePrivate.',
+        inputSchema: {
+            includePrivate: z.boolean().optional(),
+            includeArchived: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => errorResult(async () => {
+        const service = new KnowledgeService(root);
+        const result = await service.list({
+            includePrivate: args.includePrivate === true,
+            includeArchived: args.includeArchived === true,
+        });
+        return {
+            ok: result.ok,
+            catalogDigest: result.catalogDigest,
+            documents: result.records.map((record) => ({
+                documentId: record.documentId,
+                kind: record.kind,
+                lifecycle: record.lifecycle,
+                maturity: record.maturity,
+                visibility: record.visibility,
+                location: record.location,
+            })),
+            diagnostics: result.diagnostics,
+        };
+    }));
+    server.registerTool('docs_check', {
+        title: 'Check knowledge freshness',
+        description: 'Checks registered documents for freshness and source drift.',
+        inputSchema: { includePrivate: z.boolean().optional() },
+        annotations: { readOnlyHint: true },
+    }, async (args) => errorResult(async () => {
+        const service = new KnowledgeService(root);
+        const result = await service.check({
+            includePrivate: args.includePrivate === true,
+        });
+        return {
+            ok: result.ok,
+            summary: result.summary,
+            coverage: result.coverage,
+            diagnostics: result.diagnostics,
+        };
+    }));
+    server.registerTool('code_status', {
+        title: 'Code index status',
+        description: 'Reports the selected repository code-index identity and health without preparing it.',
+        inputSchema: { repo: z.string().min(1).max(128) },
+        annotations: { readOnlyHint: true },
+    }, async (args) => errorResult(async () => {
+        const service = new CodeIntelligenceService(root);
+        const result = await service.status({ repositoryId: args.repo });
+        return {
+            ok: result.ok,
+            health: result.health,
+            registrationPresent: result.registrationPresent,
+            registrationPath: result.registrationPath,
+            diagnostics: result.diagnostics,
+        };
+    }));
+    server.registerTool('code_query', {
+        title: 'Query repository code',
+        description: 'Bounded code query for one selected repository. Semantic kinds need a prepared index; text works without one.',
+        inputSchema: {
+            repo: z.string().min(1).max(128),
+            kind: z.enum(['explore', 'symbol', 'references', 'impact', 'text']),
+            query: z.string().min(1).max(4096),
+            limit: z.number().int().min(1).max(100).optional(),
+            maxBytes: z.number().int().min(1).max(1_048_576).optional(),
+        },
+        annotations: { readOnlyHint: true },
+    }, async (args) => errorResult(async () => {
+        const service = new CodeIntelligenceService(root);
+        const result = await service.query({
+            root,
+            repositoryId: args.repo,
+            kind: args.kind,
+            query: args.query,
+            ...(args.limit === undefined && args.maxBytes === undefined
+                ? {}
+                : {
+                    limits: {
+                        ...(args.limit === undefined
+                            ? {}
+                            : { maxResults: args.limit }),
+                        ...(args.maxBytes === undefined
+                            ? {}
+                            : { maxBytes: args.maxBytes }),
+                    },
+                }),
+        });
+        return {
+            ok: result.ok,
+            provider: result.result?.provider ?? null,
+            coverage: result.result?.coverage ?? null,
+            items: result.result?.items ?? [],
+            health: result.health,
+            diagnostics: result.diagnostics,
+        };
+    }));
+    server.registerTool('checkpoint', {
+        title: 'Write a task checkpoint',
+        description: 'Writes an advisory checkpoint for handoff. Requires apply: true; a checkpoint is context, not permission to execute.',
+        inputSchema: {
+            task: z.string().min(1).max(256),
+            objective: z.string().min(1).max(4000),
+            acceptance: z.array(z.string().min(1).max(1000)).max(32).optional(),
+            constraints: z.array(z.string().min(1).max(1000)).max(32).optional(),
+            decisions: z.array(z.string().min(1).max(1000)).max(32).optional(),
+            attempted: z.array(z.string().min(1).max(1000)).max(32).optional(),
+            nextActions: z.array(z.string().min(1).max(1000)).max(32).optional(),
+            limitations: z.array(z.string().min(1).max(1000)).max(32).optional(),
+            artifacts: z.array(z.string().min(1).max(2048)).max(32).optional(),
+            contextCompleteness: z.enum(['complete', 'partial']).optional(),
+            authorSession: z.string().min(1).max(256).optional(),
+            nativeHarness: z.enum(['pi', 'codex', 'claude', 'unknown']).optional(),
+            nativeSession: z.string().min(1).max(256).optional(),
+            apply: z.boolean(),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => errorResult(async () => {
+        if (args.apply !== true) {
+            return {
+                ok: false,
+                status: 'confirmation_required',
+                message: 'checkpoint writes state; call again with apply: true after the user agrees.',
+            };
+        }
+        const nativeRefs = args.nativeSession === undefined
+            ? []
+            : [
+                {
+                    harness: args.nativeHarness ?? 'unknown',
+                    sessionId: args.nativeSession,
+                    turnId: null,
+                    runId: null,
+                },
+            ];
+        const service = new CheckpointService(root);
+        const result = await service.save({
+            taskId: args.task,
+            objective: args.objective,
+            ...(args.acceptance === undefined
+                ? {}
+                : { acceptance: args.acceptance }),
+            ...(args.constraints === undefined
+                ? {}
+                : { constraints: args.constraints }),
+            ...(args.decisions === undefined
+                ? {}
+                : { decisions: args.decisions }),
+            ...(args.attempted === undefined
+                ? {}
+                : { attempted: args.attempted }),
+            ...(args.nextActions === undefined
+                ? {}
+                : { nextActions: args.nextActions }),
+            ...(args.limitations === undefined
+                ? {}
+                : { limitations: args.limitations }),
+            ...(args.artifacts === undefined
+                ? {}
+                : { artifacts: args.artifacts }),
+            ...(args.contextCompleteness === undefined
+                ? {}
+                : { contextCompleteness: args.contextCompleteness }),
+            ...(args.authorSession === undefined
+                ? {}
+                : { authorSession: args.authorSession }),
+            ...(nativeRefs.length === 0 ? {} : { nativeRefs }),
+        });
+        return {
+            ok: result.ok,
+            status: result.status,
+            checkpointId: result.checkpoint?.checkpointId ?? null,
+            checkpointPath: result.checkpointPath,
+            diagnostics: result.diagnostics,
+            residualPaths: result.residualPaths,
+        };
+    }));
+    server.registerTool('docs_scan', {
+        title: 'Scan knowledge sources',
+        description: 'Registers documents discovered under the configured knowledge sources. Without apply it only reports candidates.',
+        inputSchema: { apply: z.boolean().optional() },
+        annotations: { readOnlyHint: false },
+    }, async (args) => errorResult(async () => {
+        const result = await scanDiscoveredDocuments(root, {
+            apply: args.apply === true,
+        });
+        return result;
+    }));
+    server.registerTool('code_prepare', {
+        title: 'Prepare a repository code index',
+        description: 'Registers the selected repository index and optionally runs the external engine. Without apply it only reports the plan.',
+        inputSchema: {
+            repo: z.string().min(1).max(128),
+            apply: z.boolean().optional(),
+            rebuild: z.boolean().optional(),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => errorResult(async () => {
+        const service = new CodeIntelligenceService(root);
+        const result = await service.prepare({
+            root,
+            repositoryId: args.repo,
+            apply: args.apply === true,
+            rebuild: args.rebuild === true,
+        });
+        return {
+            ok: result.ok,
+            status: result.status,
+            plan: result.plan,
+            health: result.health,
+            registrationPath: result.registrationPath,
+            diagnostics: result.diagnostics,
+        };
+    }));
+    server.registerTool('runtime_install', {
+        title: 'Install the durable runtime',
+        description: 'Installs and binds a durable runtime copy. Requires apply: true; the default source is the running package.',
+        inputSchema: {
+            from: z.enum(['self', 'tarball', 'version']).optional(),
+            version: z.string().min(1).max(128).optional(),
+            tarball: z.string().min(1).max(4096).optional(),
+            apply: z.boolean(),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => errorResult(async () => {
+        const from = args.from ?? 'self';
+        const version = args.version ?? getPackageInfo().version;
+        if (args.apply !== true) {
+            return {
+                ok: false,
+                status: 'confirmation_required',
+                message: 'runtime_install writes a durable copy and machine.json; call again with apply: true.',
+                version,
+                from,
+            };
+        }
+        if (from === 'self') {
+            const result = await ensureDefaultRuntime(root, version);
+            return {
+                ok: result.ok && result.completion,
+                completion: result.completion,
+                runtime: result.runtime,
+                diagnostics: result.diagnostics,
+            };
+        }
+        const tarball = args.tarball;
+        if (from === 'tarball' && tarball === undefined) {
+            return {
+                ok: false,
+                message: 'from: tarball requires the tarball path.',
+            };
+        }
+        const installed = await installRuntime({
+            version,
+            source: from === 'tarball' && tarball !== undefined
+                ? { kind: 'tarball', path: tarball }
+                : { kind: 'version' },
+            packageName: getPackageInfo().name,
+        });
+        const bound = await bindAndRecordRuntime(root, installed);
+        return {
+            ok: bound.ok && bound.completion,
+            completion: bound.completion,
+            runtime: installed,
+            diagnostics: bound.diagnostics,
+        };
+    }));
+    server.registerTool('collab_prepare', {
+        title: 'Prepare a bounded collaboration',
+        description: 'Builds a collaboration goal and a declared capability card from an objective and explicit resources, then claims them. A declared card cannot authorize a work launch.',
+        inputSchema: {
+            domainRoot: z.string().min(1).max(4096),
+            objective: z.string().min(1).max(4000),
+            task: z.string().min(1).max(128),
+            acceptance: z.array(z.string().min(1).max(1000)).min(1).max(32),
+            resources: z
+                .array(z.object({
+                path: z.string().min(1).max(4096),
+                access: z.enum(['read', 'write']),
+            }))
+                .min(1)
+                .max(32),
+            coordinatorSession: z.string().min(1).max(256),
+            assigneeSession: z.string().min(1).max(256),
+            harness: z.enum(['pi', 'codex', 'claude']).optional(),
+            subtaskId: z.string().min(1).max(128).optional(),
+            attempt: z.number().int().min(1).max(1000).optional(),
+            phase: z
+                .enum(['discovery', 'implementation', 'review', 'handoff', 'fix'])
+                .optional(),
+            prompt: z.string().min(1).max(20000).optional(),
+        },
+        annotations: { readOnlyHint: false },
+    }, async (args) => errorResult(async () => {
+        const result = await prepareFromObjective({
+            domainRoot: args.domainRoot,
+            objective: args.objective,
+            taskId: args.task,
+            acceptance: args.acceptance,
+            resources: args.resources,
+            coordinatorSession: args.coordinatorSession,
+            assigneeSession: args.assigneeSession,
+            ...(args.harness === undefined ? {} : { harness: args.harness }),
+            ...(args.subtaskId === undefined
+                ? {}
+                : { subtaskId: args.subtaskId }),
+            ...(args.attempt === undefined ? {} : { attempt: args.attempt }),
+            ...(args.phase === undefined ? {} : { phase: args.phase }),
+            ...(args.prompt === undefined ? {} : { prompt: args.prompt }),
+        });
+        return result;
+    }));
+    server.registerTool('collab_start', {
+        title: 'Start one admitted collaboration launch',
+        description: 'Performs one admitted launch with an explicit controller and returns the report. Requires confirm: true and a runtime capability card; a declared card is refused by admission.',
+        inputSchema: {
+            prepared: z.string().min(1).max(4096),
+            capabilities: z.string().min(1).max(4096),
+            controller: z.enum(['fixture', 'pi-rpc']),
+            confirm: z.boolean(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true },
+    }, async (args) => errorResult(async () => {
+        if (args.confirm !== true) {
+            return {
+                ok: false,
+                status: 'confirmation_required',
+                message: 'collab_start launches a process; the user must confirm before calling it with confirm: true.',
+            };
+        }
+        const controller = args.controller === 'fixture'
+            ? new FixtureController()
+            : new PiRpcController();
+        const started = await startPrepared(args.prepared, {
+            capabilitiesFile: args.capabilities,
+            controller,
+            controllerId: controller.id,
+        });
+        if (!started.ok)
+            return started;
+        try {
+            const finished = await finishStarted(started.value);
+            if (!finished.ok) {
+                return finished;
+            }
+            const report = submitResultReport(started.value, finished.value);
+            return {
+                ok: report.ok,
+                status: finished.value.status,
+                report,
+                finish: finished.value,
+            };
+        }
+        finally {
+            await started.value.session.dispose?.().catch(() => undefined);
+        }
+    }));
+    server.registerTool('runtime_status', {
+        title: 'Runtime status',
+        description: 'Reports the workspace runtime binding and passive runtime state.',
+        annotations: { readOnlyHint: true },
+    }, async () => errorResult(async () => {
+        const machine = await inspectMachineConfig(root);
+        const binding = machine.value?.runtime ?? null;
+        if (binding === null) {
+            return { ok: true, binding: null, runtime: null };
+        }
+        const state = await inspectRuntimeStatePassive(binding.version);
+        return {
+            ok: true,
+            binding,
+            runtime: {
+                version: state.version,
+                status: state.status,
+                packageDigestMatch: state.packageDigestMatch,
+                executableExists: state.executableExists,
+            },
+            diagnostics: state.diagnostics,
+        };
+    }));
+    return server;
+}
+export async function runMcpServer(root) {
+    const server = createPappraMcpServer({ root });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}

package/dist/schemas/workspace.d.ts

@@ -59,6 +59,9 @@ export declare const workspaceValidationSchema: z.ZodObject<{
     executable: z.ZodString;
     args: z.ZodArray<z.ZodString>;
 }, z.core.$strict>;
+export declare const workspaceContinuitySchema: z.ZodObject<{
+    autoResume: z.ZodBoolean;
+}, z.core.$strict>;
 export declare const workspaceConfigSchema: z.ZodObject<{
     schema: z.ZodLiteral<"pappra/workspace/1">;
     workspaceId: z.ZodUUID;
@@ -103,6 +106,9 @@ export declare const workspaceConfigSchema: z.ZodObject<{
     }, z.core.$strict>>;
     excludes: z.ZodArray<z.ZodString>;
     extensions: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    continuity: z.ZodOptional<z.ZodObject<{
+        autoResume: z.ZodBoolean;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;
 export type WorkspaceRepository = z.infer<typeof workspaceRepositorySchema>;

package/dist/schemas/workspace.js

@@ -44,6 +44,9 @@ export const workspaceValidationSchema = z.strictObject({
     executable: executableSchema,
     args: z.array(argumentSchema).max(256),
 });
+export const workspaceContinuitySchema = z.strictObject({
+    autoResume: z.boolean(),
+});
 export const workspaceConfigSchema = z.strictObject({
     schema: z.literal(WORKSPACE_SCHEMA),
     workspaceId: z.uuid(),
@@ -55,6 +58,7 @@ export const workspaceConfigSchema = z.strictObject({
     validation: z.array(workspaceValidationSchema).max(128),
     excludes: z.array(portablePathSchema).max(128),
     extensions: z.record(z.string().min(1).max(128), z.unknown()),
+    continuity: workspaceContinuitySchema.optional(),
 });
 function pathDiagnostic(value, source, fieldPointer, label) {
     const hint = 'Use a workspace-relative path such as "docs" or "repos/app".';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phyzess/pappra",
-  "version": "0.1.0-beta.12",
+  "version": "0.1.0-beta.13",
   "description": "Portable workspace knowledge and continuity for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -98,6 +98,7 @@
   },
   "dependencies": {
     "@clack/prompts": "1.8.1",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "zod": "4.6.6"
   },
   "repository": {

package/skills/pappra/references/operations.md

@@ -21,6 +21,8 @@
   host. Codex 0.163.0 loads hooks only from `$CODEX_HOME/hooks.json`, so use
   `install --host codex --scope user`; `bundle --marketplace` exports a plugin
   directory without registering it, and `install --mode plugin` fails closed.
+- `pappra mcp` starts the stdio MCP server; `pappra host mcp install --host <name> --apply`
+  registers it. `pappra task pin <id> --auto-resume` controls hook resume injection.
 - `pappra collab <prepare|run|query>` runs one bounded collaboration request.
   `run` requires `--controller fixture|pi-rpc`; `pi-rpc` launches a real Pi RPC
   session.