@parall/cli 1.33.0 → 1.35.0

package/dist/commands/mcp.d.ts

@@ -1,3 +1,8 @@
 import { Command } from 'commander';
+/**
+ * Adds the `mcp` subcommand to the CLI, which runs a Parall MCP server over stdio.
+ * On invocation it resolves credentials, registers all wiki tools, and connects a
+ * stdio transport (server lifecycle log goes to stderr to keep stdout clean for the protocol).
+ */
 export declare function registerMcpCommands(program: Command): void;
 //# sourceMappingURL=mcp.d.ts.map

package/dist/commands/mcp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAmBpC,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,QAulBnD"}
+{"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/commands/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgCpC;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,OAAO,QAmBnD"}

package/dist/commands/mcp.js

@@ -1,8 +1,33 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import * as z from 'zod/v4';
-import { resolveCredentials, resolveRuntimeContext } from '../lib/client.js';
-import { getWikiBlob, getWikiChangesetDiff, getWikiOutline, queryWiki, getWikiSection, getWikiTree, getWikiWorkspaceDiff, getWikiWorkspaceStatus, listWikis, proposeWikiChangeset, searchWiki, } from '../lib/wiki.js';
+import { resolveCredentials } from '../lib/client.js';
+import { buildWikiTools } from '../lib/wiki-tools.js';
+/**
+ * Registers a single wiki tool on the MCP server, wiring its schema/annotations and
+ * adapting the tool's `{ text, structuredContent }` result into MCP's content envelope.
+ */
+function registerWikiTool(server, tool) {
+    server.registerTool(tool.name, {
+        title: tool.title,
+        description: tool.description,
+        annotations: {
+            readOnlyHint: tool.readOnly,
+        },
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+    }, async (args) => {
+        const result = await tool.handler(args);
+        return {
+            content: [{ type: 'text', text: result.text }],
+            structuredContent: result.structuredContent,
+        };
+    });
+}
+/**
+ * Adds the `mcp` subcommand to the CLI, which runs a Parall MCP server over stdio.
+ * On invocation it resolves credentials, registers all wiki tools, and connects a
+ * stdio transport (server lifecycle log goes to stderr to keep stdout clean for the protocol).
+ */
 export function registerMcpCommands(program) {
     program
         .command('mcp')
@@ -13,485 +38,9 @@ export function registerMcpCommands(program) {
             name: 'parall-mcp',
             version: '1.0.0',
         });
-        server.registerTool('wiki_list', {
-            title: 'List Parall Wikis',
-            description: 'List Parall wiki repositories that the current credentials can access.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            outputSchema: {
-                wikis: z.array(z.object({
-                    id: z.string(),
-                    slug: z.string(),
-                    name: z.string(),
-                    default_branch: z.string(),
-                })),
-            },
-        }, async () => {
-            const wikis = await listWikis(ctx);
-            const structuredContent = {
-                wikis: wikis.map((wiki) => ({
-                    id: wiki.id,
-                    slug: wiki.slug,
-                    name: wiki.name,
-                    default_branch: wiki.default_branch,
-                })),
-            };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
-                structuredContent,
-            };
-        });
-        server.registerTool('wiki_tree', {
-            title: 'Browse Wiki Tree',
-            description: 'List files and folders under a Parall wiki path.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                path: z.string().optional().describe('Optional tree path prefix inside the wiki'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                path: z.string(),
-                entries: z.array(z.object({
-                    name: z.string(),
-                    path: z.string(),
-                    type: z.enum(['tree', 'blob']),
-                    size: z.number().optional(),
-                })),
-            },
-        }, async ({ wiki, path }) => {
-            const result = await getWikiTree(ctx, wiki, { path });
-            const structuredContent = {
-                wiki_id: result.wiki.id,
-                wiki_slug: result.wiki.slug,
-                wiki_name: result.wiki.name,
-                path: result.path,
-                entries: result.entries,
-            };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
-                structuredContent,
-            };
-        });
-        server.registerTool('wiki_status', {
-            title: 'Inspect Wiki Workspace Status',
-            description: 'Inspect the current local mounted wiki workspace before proposing changes.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                mount_path: z.string(),
-                mode: z.enum(['read_only', 'read_write']),
-                default_ref: z.string(),
-                changed_paths: z.array(z.string()),
-                diff_files: z.array(z.object({
-                    path: z.string(),
-                    additions: z.number(),
-                    deletions: z.number(),
-                })),
-                dirty: z.boolean(),
-                source: z.literal('local_mount'),
-            },
-        }, async ({ wiki }) => {
-            const result = await getWikiWorkspaceStatus(ctx, wiki);
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                structuredContent: result,
-            };
-        });
-        server.registerTool('wiki_diff', {
-            title: 'Read Wiki Workspace Diff',
-            description: 'Read the current unified diff for a local mounted wiki workspace.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                mount_path: z.string(),
-                changed_paths: z.array(z.string()),
-                diff_files: z.array(z.object({
-                    path: z.string(),
-                    additions: z.number(),
-                    deletions: z.number(),
-                })),
-                patch: z.string(),
-                source: z.literal('local_mount'),
-            },
-        }, async ({ wiki }) => {
-            const result = await getWikiWorkspaceDiff(ctx, wiki);
-            return {
-                content: [{ type: 'text', text: result.patch || JSON.stringify(result, null, 2) }],
-                structuredContent: result,
-            };
-        });
-        server.registerTool('wiki_blob', {
-            title: 'Read Wiki File',
-            description: 'Read a file from a Parall wiki and return its text content.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                path: z.string().describe('File path inside the wiki'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                content: z.string(),
-                sha256: z.string(),
-                size: z.number(),
-            },
-        }, async ({ wiki, path }) => {
-            const result = await getWikiBlob(ctx, wiki, { path });
-            const structuredContent = {
-                wiki_id: result.wiki.id,
-                wiki_slug: result.wiki.slug,
-                wiki_name: result.wiki.name,
-                content: result.content,
-                size: result.size,
-            };
-            return {
-                content: [
-                    { type: 'text', text: result.content || JSON.stringify(structuredContent, null, 2) },
-                ],
-                structuredContent,
-            };
-        });
-        server.registerTool('wiki_search', {
-            title: 'Search Wiki Markdown',
-            description: 'Search Markdown headings and section bodies inside a Parall wiki. Prefers local mounts when no ref is supplied and agent env is available; otherwise falls back to the Parall API.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                query: z.string().describe('Search query'),
-                ref: z.string().optional().describe('Optional git ref for API-backed search'),
-                path_prefix: z
-                    .string()
-                    .optional()
-                    .describe('Restrict search to a file or directory path prefix'),
-                limit: z
-                    .number()
-                    .int()
-                    .positive()
-                    .max(20)
-                    .optional()
-                    .describe('Maximum number of results; default 5'),
-                include_content: z
-                    .boolean()
-                    .optional()
-                    .describe('Include full matched section content in each result'),
-            },
-            outputSchema: {
-                results: z.array(z.object({
-                    wiki_id: z.string(),
-                    wiki_slug: z.string(),
-                    wiki_name: z.string(),
-                    node_id: z.string(),
-                    path: z.string(),
-                    title: z.string(),
-                    heading_path: z.array(z.string()).optional(),
-                    section_path: z.string(),
-                    level: z.number(),
-                    start_line: z.number(),
-                    end_line: z.number(),
-                    score: z.number(),
-                    snippet: z.string(),
-                    content: z.string().optional(),
-                    source: z.enum(['local_mount', 'api']),
-                })),
-            },
-        }, async ({ wiki, query, ref, path_prefix: pathPrefix, limit, include_content: includeContent, }) => {
-            const results = await searchWiki(ctx, wiki, query, {
-                ref,
-                pathPrefix,
-                limit,
-                includeContent,
-            });
-            const structuredContent = { results };
-            return {
-                content: [{ type: 'text', text: JSON.stringify(structuredContent, null, 2) }],
-                structuredContent,
-            };
-        });
-        server.registerTool('wiki_query', {
-            title: 'Query Wiki Structurally',
-            description: 'Run a tree-aware wiki query that first narrows candidate documents and then selects the best sections.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                query: z.string().describe('Natural-language query'),
-                ref: z.string().optional().describe('Optional git ref for API-backed queries'),
-                path_prefix: z
-                    .string()
-                    .optional()
-                    .describe('Restrict the query to a file or directory path prefix'),
-                limit: z
-                    .number()
-                    .int()
-                    .positive()
-                    .max(20)
-                    .optional()
-                    .describe('Maximum number of section results; default 5'),
-                include_content: z
-                    .boolean()
-                    .optional()
-                    .describe('Include full matched section content in each result'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                query: z.string(),
-                ref: z.string().optional(),
-                path_prefix: z.string().optional(),
-                generated_at: z.string(),
-                file_count: z.number(),
-                source: z.enum(['local_mount', 'api']),
-                documents: z.array(z.object({
-                    path: z.string(),
-                    title: z.string(),
-                    score: z.number(),
-                    matched_headings: z.array(z.string()),
-                    node_count: z.number(),
-                })),
-                sections: z.array(z.object({
-                    wiki_id: z.string(),
-                    wiki_slug: z.string(),
-                    wiki_name: z.string(),
-                    node_id: z.string(),
-                    path: z.string(),
-                    title: z.string(),
-                    heading_path: z.array(z.string()).optional(),
-                    section_path: z.string(),
-                    level: z.number(),
-                    start_line: z.number(),
-                    end_line: z.number(),
-                    score: z.number(),
-                    document_score: z.number(),
-                    snippet: z.string(),
-                    content: z.string().optional(),
-                    source: z.enum(['local_mount', 'api']),
-                    reasoning: z.array(z.string()),
-                })),
-            },
-        }, async ({ wiki, query, ref, path_prefix: pathPrefix, limit, include_content: includeContent, }) => {
-            const result = await queryWiki(ctx, wiki, query, {
-                ref,
-                pathPrefix,
-                limit,
-                includeContent,
-            });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                structuredContent: result,
-            };
-        });
-        server.registerTool('wiki_outline', {
-            title: 'Read Wiki Outline',
-            description: 'Return the structural node outline for a Parall wiki or a path prefix within it.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                ref: z.string().optional().describe('Optional git ref for API-backed outline'),
-                path_prefix: z
-                    .string()
-                    .optional()
-                    .describe('Restrict outline to a file or directory path prefix'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                ref: z.string().optional(),
-                path_prefix: z.string().optional(),
-                generated_at: z.string(),
-                file_count: z.number(),
-                source: z.enum(['local_mount', 'api']),
-                nodes: z.array(z.object({
-                    wiki_id: z.string(),
-                    wiki_slug: z.string(),
-                    wiki_name: z.string(),
-                    node_id: z.string(),
-                    path: z.string(),
-                    title: z.string(),
-                    heading_path: z.array(z.string()).optional(),
-                    section_path: z.string(),
-                    level: z.number(),
-                    start_line: z.number(),
-                    end_line: z.number(),
-                })),
-            },
-        }, async ({ wiki, ref, path_prefix: pathPrefix }) => {
-            const outline = await getWikiOutline(ctx, wiki, { ref, pathPrefix });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(outline, null, 2) }],
-                structuredContent: outline,
-            };
-        });
-        server.registerTool('wiki_section', {
-            title: 'Read Wiki Section',
-            description: 'Read a specific Markdown section from a Parall wiki by node ID. Node IDs come from `wiki_search` results.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                node_id: z.string().describe('Section node ID returned by wiki_search'),
-                ref: z
-                    .string()
-                    .optional()
-                    .describe('Optional git ref; when set, reads from the Parall API instead of a local mount'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                node_id: z.string(),
-                path: z.string(),
-                title: z.string(),
-                heading_path: z.array(z.string()).optional(),
-                section_path: z.string(),
-                level: z.number(),
-                start_line: z.number(),
-                end_line: z.number(),
-                content: z.string(),
-                source: z.enum(['local_mount', 'api']),
-            },
-        }, async ({ wiki, node_id: nodeId, ref }) => {
-            const section = await getWikiSection(ctx, wiki, { nodeId, ref });
-            return {
-                content: [{ type: 'text', text: section.content || JSON.stringify(section, null, 2) }],
-                structuredContent: section,
-            };
-        });
-        server.registerTool('wiki_changeset_diff', {
-            title: 'Read Wiki Changeset Diff',
-            description: 'Fetch the unified diff and changed file summary for a Parall wiki changeset.',
-            annotations: {
-                readOnlyHint: true,
-            },
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                changeset_id: z.string().describe('Wiki changeset ID'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                changeset_id: z.string(),
-                diff: z.object({
-                    patch: z.string(),
-                    files: z.array(z.object({
-                        path: z.string(),
-                        additions: z.number(),
-                        deletions: z.number(),
-                    })),
-                }),
-            },
-        }, async ({ wiki, changeset_id: changesetId }) => {
-            const diff = await getWikiChangesetDiff(ctx, wiki, changesetId);
-            return {
-                content: [{ type: 'text', text: diff.diff.patch || JSON.stringify(diff, null, 2) }],
-                structuredContent: diff,
-            };
-        });
-        server.registerTool('wiki_propose', {
-            title: 'Propose Wiki Changeset',
-            description: 'Create or update a wiki changeset from the current local mounted wiki workspace. Unprotected changesets may auto-merge immediately.',
-            inputSchema: {
-                wiki: z.string().describe('Wiki slug or ID'),
-                title: z.string().min(1).describe('Changeset title'),
-                message: z
-                    .string()
-                    .optional()
-                    .describe('Changeset commit message (supports prll:// refs)'),
-                changeset_id: z.string().optional().describe('Existing changeset ID to update'),
-                source_chat_id: z
-                    .string()
-                    .optional()
-                    .describe('Optional source chat ID for approval workflow linkage'),
-                source_message_id: z
-                    .string()
-                    .optional()
-                    .describe('Optional source message ID for approval workflow linkage'),
-                source_run_id: z
-                    .string()
-                    .optional()
-                    .describe('Optional source run ID for approval workflow linkage'),
-            },
-            outputSchema: {
-                wiki_id: z.string(),
-                wiki_slug: z.string(),
-                wiki_name: z.string(),
-                mount_path: z.string(),
-                changed_paths: z.array(z.string()),
-                status: z.string(),
-                auto_merged: z.boolean(),
-                requires_review: z.boolean(),
-                next_action: z.string(),
-                post_merge_sync: z
-                    .object({
-                    applied: z.number(),
-                    fastForwarded: z.number(),
-                    conflicts: z.array(z.unknown()),
-                    failed: z.array(z.unknown()),
-                })
-                    .nullable(),
-                post_merge_sync_error: z.string().nullable(),
-                diff_files: z.array(z.object({
-                    path: z.string(),
-                    additions: z.number(),
-                    deletions: z.number(),
-                })),
-                source: z.literal('local_mount'),
-                changeset: z
-                    .object({
-                    id: z.string(),
-                    wiki_id: z.string(),
-                    title: z.string(),
-                    status: z.string(),
-                    changed_paths: z.array(z.string()).optional(),
-                })
-                    .passthrough(),
-            },
-        }, async ({ wiki, title, message, changeset_id: changesetId, source_chat_id: sourceChatId, source_message_id: sourceMessageId, source_run_id: sourceRunId, }) => {
-            const runtime = resolveRuntimeContext();
-            const result = await proposeWikiChangeset(ctx, wiki, {
-                title,
-                message,
-                changesetId,
-                sourceChatId: sourceChatId ?? runtime.chatId,
-                sourceMessageId: sourceMessageId ?? runtime.triggerMessageId,
-                sourceRunId: sourceRunId ?? runtime.sessionId,
-            });
-            return {
-                content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-                structuredContent: result,
-            };
-        });
+        for (const tool of buildWikiTools(ctx)) {
+            registerWikiTool(server, tool);
+        }
         const transport = new StdioServerTransport();
         await server.connect(transport);
         console.error('parall MCP server running on stdio');

package/dist/commands/wiki.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"wiki.d.ts","sourceRoot":"","sources":["../../src/commands/wiki.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAq2BpD"}
+{"version":3,"file":"wiki.d.ts","sourceRoot":"","sources":["../../src/commands/wiki.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAwBpC,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,QAy3BpD"}