unicommand 0.0.4 → 0.1.0

package/README.md

@@ -164,6 +164,51 @@ The generated shim runs `src/cli.ts`, sets the package program-name env var, and
 
 </div>
 
+<div align="center">
+
+<details>
+<summary>Show MCP server options</summary>
+<br />
+
+<div align="left">
+
+Bind values to the whole MCP server process, such as the account a server acts as:
+
+```ts
+import { startPackageCommandMcpServer } from 'unicommand';
+
+await startPackageCommandMcpServer({
+  importMetaUrl: import.meta.url,
+  serverOptions: [{ name: 'account', description: 'Account email', required: true }],
+  instructions: ({ account }) => `This server acts as ${account}.`,
+  getContext: ({ account }) => createContext(account),
+});
+```
+
+- A value comes from `--account <value>` or, when absent, from `<PACKAGE>_ACCOUNT` (for example `GSHEETS_ACCOUNT`). Set `env` on the option to use another variable.
+- A bound option disappears from every tool input schema and is injected into each call. A call that passes a different value fails.
+- A missing required option stops the server at startup with a message on stderr.
+
+Choose where each command option appears:
+
+- `mcp: false` keeps an option CLI only, such as an output format or a local export path.
+- `mcp: 'required'` makes an option required in the MCP schema while the CLI keeps it optional.
+
+Run one MCP tool command without starting the server by appending its name and flags. The JSON result goes to stdout; failures exit non-zero with a message on stderr:
+
+```sh
+my-mcp --account me@example.com auth status
+my-mcp --account me@example.com auth begin --redirect-uri http://127.0.0.1:4000/callback
+```
+
+The server negotiates the protocol version, answers `ping`, handles requests concurrently, reports tool failures with `isError: true` and unknown tools as JSON-RPC errors, and only emits standard tool annotations. Side effects and confirmation needs are added to the tool description.
+
+</div>
+
+</details>
+
+</div>
+
 ## 🛠 Development
 
 <div align="center">
@@ -185,6 +230,7 @@ Run checks:
 ```sh
 pnpm check:fix
 pnpm typecheck
+pnpm test
 pnpm build
 pnpm knip
 ```

package/dist/index.d.ts

@@ -23,6 +23,7 @@ type CommandOptionDefinition = {
     description: string;
     aliases?: readonly string[];
     config?: CreateOptionCommandOpts;
+    mcp?: boolean | 'required';
     negated?: boolean;
     schema?: JsonSchemaProperty;
     value?: string;
@@ -94,6 +95,7 @@ declare const commandDefinitionToInputSchema: (definition: CommandDefinition) =>
     additionalProperties: boolean;
 };
 declare const commandOptionSynopsis: (option: CommandOptionDefinition) => string;
+declare const optionInputName: (option: CommandOptionDefinition) => string;
 
 type ProgramHelpData = {
     binName: string;
@@ -106,6 +108,29 @@ declare const setProgramHelpData: (program: Program, data: ProgramHelpData) => v
 declare const isGlobalHelpRequest: (args: readonly string[]) => boolean;
 declare const printProgramHelp: (program: Program) => Promise<void>;
 
+type McpServerOptionDefinition = {
+    name: string;
+    description: string;
+    env?: string;
+    required?: boolean;
+};
+type McpServerOptionValues = Record<string, string>;
+type McpServerArgv = {
+    flags: Record<string, string>;
+    positionals: string[];
+};
+declare const parseMcpServerArgv: (argv: readonly string[]) => McpServerArgv;
+declare const mcpServerOptionEnvName: (envPrefix: string, option: McpServerOptionDefinition) => string;
+declare const resolveMcpServerOptions: ({ argvFlags, definitions, env, envPrefix, }: {
+    argvFlags: Record<string, string>;
+    definitions: readonly McpServerOptionDefinition[];
+    env: NodeJS.ProcessEnv;
+    envPrefix: string;
+}) => McpServerOptionValues;
+declare const withoutMcpServerOptionFlags: (flags: Record<string, string>, definitions: readonly McpServerOptionDefinition[]) => {
+    [k: string]: string;
+};
+
 type McpToolDefinition = {
     name: string;
     description: string;
@@ -116,8 +141,6 @@ type McpToolDefinition = {
         destructiveHint?: boolean;
         idempotentHint?: boolean;
         openWorldHint?: boolean;
-        requiresConfirmation?: boolean;
-        sideEffects?: string[];
     };
 };
 type JsonRpcRequest = {
@@ -159,6 +182,8 @@ type CommandResourceRoute = {
 };
 type CreateMcpServerOptions = {
     name: string;
+    version?: string;
+    instructions?: string;
     tools: McpToolDefinition[];
     resources?: McpResourceDefinition[];
     resourceTemplates?: McpResourceTemplateDefinition[];
@@ -170,13 +195,21 @@ type CreateSingleToolMcpServerOptions = {
     tool: McpToolDefinition;
     callTool: (args: Record<string, unknown>) => Promise<unknown> | unknown;
 };
+type McpServerContextFactory<TContext> = (serverOptions: McpServerOptionValues) => Promise<TContext> | TContext;
+type McpServerInstructions = string | ((serverOptions: McpServerOptionValues) => string);
 type CreateCommandMcpServerOptions<TContext> = {
+    argv?: readonly string[];
     commandsDir?: string;
-    getContext?: () => Promise<TContext> | TContext;
+    env?: NodeJS.ProcessEnv;
+    envPrefix?: string;
+    getContext?: McpServerContextFactory<TContext>;
     importCommandModule?: CommandModuleImporter;
     importMetaUrl: string;
+    instructions?: McpServerInstructions;
     name: string;
     prefix?: string;
+    serverOptions?: readonly McpServerOptionDefinition[];
+    version?: string;
 };
 type CreatePackageCommandMcpServerOptions<TContext> = Omit<CreateCommandMcpServerOptions<TContext>, 'name' | 'prefix'> & {
     mcpServerPrefix?: string;
@@ -191,6 +224,7 @@ type CommandMcpRoute = {
 };
 type CommandMcpRouteFactory<TContext> = (getContext: () => Promise<TContext> | TContext) => CommandMcpRoute;
 type CreateCommandMcpRouterOptions = {
+    boundOptions?: McpServerOptionValues;
     prefix?: string;
     routes: readonly CommandMcpRoute[];
 };
@@ -339,12 +373,26 @@ declare const generateReadmeCommandDocs: ({ binName, commandDefinitions, command
 declare const formatCommandDocs: (commands: readonly CommandDefinition[], binName: string) => string;
 
 declare const loadCommandMcpRoutes: <TContext>(commandsDir: string, getContext?: () => Promise<TContext> | TContext, importCommandModule?: CommandModuleImporter) => Promise<CommandMcpRoute[]>;
-declare const createCommandMcpServer: <TContext>({ commandsDir, getContext, importCommandModule, importMetaUrl, name, prefix, }: CreateCommandMcpServerOptions<TContext>) => Promise<{
+declare const createCommandMcpServer: <TContext>({ argv, commandsDir, env, envPrefix, getContext, importCommandModule, importMetaUrl, instructions, name, prefix, serverOptions, version, }: CreateCommandMcpServerOptions<TContext>) => Promise<{
+    boundOptions: McpServerOptionValues;
+    command: string | undefined;
+    runCommand: (commandName: string, flags?: Record<string, string>) => Promise<unknown>;
+    commandFlags: {
+        [k: string]: string;
+    };
+    handleRequest: (request: JsonRpcRequest) => Promise<void>;
     start: () => Promise<void>;
 }>;
+declare const runMcpCommandOnce: (routes: readonly CommandMcpRoute[], commandName: string, flags: Record<string, string>, { boundOptions }: {
+    boundOptions: McpServerOptionValues;
+}) => Promise<unknown>;
 declare const startCommandMcpServer: <TContext>(options: CreateCommandMcpServerOptions<TContext>) => Promise<void>;
-declare const startPackageCommandMcpServer: <TContext>({ importMetaUrl, mcpServerPrefix, name, prefix, ...options }: CreatePackageCommandMcpServerOptions<TContext>) => Promise<void>;
+declare const startPackageCommandMcpServer: <TContext>({ envPrefix, importMetaUrl, mcpServerPrefix, name, prefix, version, ...options }: CreatePackageCommandMcpServerOptions<TContext>) => Promise<void>;
 
+declare class McpProtocolError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
 declare const assertToolName: (expectedName: string, actualName: string | undefined) => void;
 declare const throwUnknownTool: (name: string | undefined) => never;
 
@@ -364,14 +412,14 @@ declare const resourceResult: (params: unknown, data: unknown) => {
 };
 
 declare const createCommandMcpRoute: ({ command, handler, inputSchema, outputSchema, }: CommandMcpRoute) => CommandMcpRoute;
-declare const commandMcpRouteToTool: (route: CommandMcpRoute, prefix?: string) => {
+declare const commandMcpRouteToTool: (route: CommandMcpRoute, prefix?: string, boundOptions?: McpServerOptionValues) => {
     name: string;
     description: string;
-    inputSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+    inputSchema: z.core.ZodStandardJSONSchemaPayload<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
     outputSchema: {
         type: string;
         properties: {
-            data: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+            data: z.core.ZodStandardJSONSchemaPayload<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
             progress: {
                 type: string;
                 properties: {
@@ -419,20 +467,20 @@ declare const commandMcpRouteToTool: (route: CommandMcpRoute, prefix?: string) =
         destructiveHint: boolean;
         idempotentHint: boolean;
         openWorldHint: boolean;
-        requiresConfirmation: boolean;
-        sideEffects: string[] | undefined;
     } | undefined;
 };
 declare const commandNameToMcpToolName: (name: string, prefix?: string) => string;
-declare const createCommandMcpRouter: ({ prefix, routes }: CreateCommandMcpRouterOptions) => {
+declare const commandMcpInputSchema: (route: CommandMcpRoute, boundOptions?: McpServerOptionValues) => ZodType;
+declare const commandMcpInput: (route: CommandMcpRoute, args: Record<string, unknown>, boundOptions?: McpServerOptionValues) => Record<string, unknown>;
+declare const createCommandMcpRouter: ({ boundOptions, prefix, routes, }: CreateCommandMcpRouterOptions) => {
     tools: {
         name: string;
         description: string;
-        inputSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+        inputSchema: z.core.ZodStandardJSONSchemaPayload<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
         outputSchema: {
             type: string;
             properties: {
-                data: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+                data: z.core.ZodStandardJSONSchemaPayload<ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
                 progress: {
                     type: string;
                     properties: {
@@ -480,8 +528,6 @@ declare const createCommandMcpRouter: ({ prefix, routes }: CreateCommandMcpRoute
             destructiveHint: boolean;
             idempotentHint: boolean;
             openWorldHint: boolean;
-            requiresConfirmation: boolean;
-            sideEffects: string[] | undefined;
         } | undefined;
     }[];
     resources: McpResourceDefinition[];
@@ -552,9 +598,12 @@ declare const emptyMcpInputSchema: {
 };
 
 declare const createSingleToolMcpServer: ({ serverName, tool, callTool, }: CreateSingleToolMcpServerOptions) => {
+    handleRequest: (request: JsonRpcRequest) => Promise<void>;
     start: () => Promise<void>;
 };
-declare const createMcpServer: ({ name, tools, resources, resourceTemplates, callTool, readResource, }: CreateMcpServerOptions) => {
+declare const negotiateMcpProtocolVersion: (params: unknown) => string;
+declare const createMcpServer: ({ name, version, instructions, tools, resources, resourceTemplates, callTool, readResource, }: CreateMcpServerOptions) => {
+    handleRequest: (request: JsonRpcRequest) => Promise<void>;
     start: () => Promise<void>;
 };
 
@@ -619,4 +668,4 @@ type DevCommandShimConfig = {
 declare const installCommandShim: (binDir: string, config: DevCommandShimConfig) => void;
 declare const getBinDir: (envName: string) => string;
 
-export { type CliConfig, type CommandAdapterExport, type CommandAdaptersReturn, type CommandArgumentDefinition, type CommandCompletionDefinition, type CommandDefinition, type CommandExamplesDefinition, type CommandMcpMetadata, type CommandMcpResourceMetadata, type CommandMcpRoute, type CommandMcpRouteFactory, type CommandMcpToolMetadata, type CommandModule, type CommandModuleImporter, type CommandOptionDefinition, type CommandRegistrar, type CommandRegistrarContext, type CommandResourceRoute, type CompletionConfig, type CreateCommandMcpRouterOptions, type CreateCommandMcpServerOptions, type CreateCommandProgramOptions, type CreateMcpServerOptions, type CreatePackageCommandMcpServerOptions, type CreateSingleToolMcpServerOptions, DEFAULT_COMMANDS_DIR, type DefineCommandDefinition, type DevCommandShimConfig, type GenerateReadmeCommandDocsOptions, type JsonRpcRequest, type JsonSchemaProperty, type McpResourceDefinition, type McpResourceTemplateDefinition, type McpResultEnvelope, type McpToolDefinition, PROGRAM_NAME_ENV_SUFFIX, type PackageBinEntry, type PackageCommandMetadata, type PackageJson, PackageManager, type RegisterCliCommandsFromDirectoryOptions, type RegisterParentCommandsFromDefinitionsOptions, type RegisterUpdateCommandOptions, type ResourceReadParams, type ShellCompletionSnippet, type ToolCallParams, assertToolName, commandActionInput, commandDefinitionToInputSchema, commandDefinitionToZodInputSchema, commandDefinitionsFromModules, commandExportsFromModules, commandInputString, commandInputValue, commandMcpRouteToResourceRoute, commandMcpRouteToTool, commandNameToMcpToolName, commandOptionSynopsis, commandResourceInput, commandResourceRouteToResource, commandResourceRouteToResourceTemplate, createCliRunner, createCommandAdapters, createCommandCliRunner, createCommandMcpRoute, createCommandMcpRouter, createCommandMcpServer, createCommandProgram, createMcpServer, createPackageCommandCliRunner, createSingleToolMcpServer, defineCommand, emptyMcpInputSchema, formatCommandDocs, generateReadmeCommandDocs, getBinDir, getPackageManagerFromPath, getProgramBin, getProgramConstructor, installCommandShim, installDevCommand, installPackageDevCommand, installPackageDevCommands, isCommandAdapterExport, isCommandMcpResourceMetadata, isCommandMcpToolMetadata, isDirectRun, isGlobalHelpRequest, isResourceTemplate, loadCommandMcpRoutes, loadCommandModules, loadCommandModulesFromFiles, mcpToolOutputSchema, normalizeCommandInputAliases, packageBinEntry, packageCommandMetadata, packageEnvPrefix, packageRoot, printProgramHelp, readPackageJson, registerCliCommandsFromDirectory, registerCommand, registerCompletionCommand, registerParentCommandsFromDefinitions, registerUpdateCommand, resourceResult, setProgramHelpData, shortPackageName, startCommandMcpServer, startPackageCommandMcpServer, throwUnknownTool, uninstallDevCommand, uninstallPackageDevCommand, uninstallPackageDevCommands };
+export { type CliConfig, type CommandAdapterExport, type CommandAdaptersReturn, type CommandArgumentDefinition, type CommandCompletionDefinition, type CommandDefinition, type CommandExamplesDefinition, type CommandMcpMetadata, type CommandMcpResourceMetadata, type CommandMcpRoute, type CommandMcpRouteFactory, type CommandMcpToolMetadata, type CommandModule, type CommandModuleImporter, type CommandOptionDefinition, type CommandRegistrar, type CommandRegistrarContext, type CommandResourceRoute, type CompletionConfig, type CreateCommandMcpRouterOptions, type CreateCommandMcpServerOptions, type CreateCommandProgramOptions, type CreateMcpServerOptions, type CreatePackageCommandMcpServerOptions, type CreateSingleToolMcpServerOptions, DEFAULT_COMMANDS_DIR, type DefineCommandDefinition, type DevCommandShimConfig, type GenerateReadmeCommandDocsOptions, type JsonRpcRequest, type JsonSchemaProperty, McpProtocolError, type McpResourceDefinition, type McpResourceTemplateDefinition, type McpResultEnvelope, type McpServerArgv, type McpServerContextFactory, type McpServerInstructions, type McpServerOptionDefinition, type McpServerOptionValues, type McpToolDefinition, PROGRAM_NAME_ENV_SUFFIX, type PackageBinEntry, type PackageCommandMetadata, type PackageJson, PackageManager, type RegisterCliCommandsFromDirectoryOptions, type RegisterParentCommandsFromDefinitionsOptions, type RegisterUpdateCommandOptions, type ResourceReadParams, type ShellCompletionSnippet, type ToolCallParams, assertToolName, commandActionInput, commandDefinitionToInputSchema, commandDefinitionToZodInputSchema, commandDefinitionsFromModules, commandExportsFromModules, commandInputString, commandInputValue, commandMcpInput, commandMcpInputSchema, commandMcpRouteToResourceRoute, commandMcpRouteToTool, commandNameToMcpToolName, commandOptionSynopsis, commandResourceInput, commandResourceRouteToResource, commandResourceRouteToResourceTemplate, createCliRunner, createCommandAdapters, createCommandCliRunner, createCommandMcpRoute, createCommandMcpRouter, createCommandMcpServer, createCommandProgram, createMcpServer, createPackageCommandCliRunner, createSingleToolMcpServer, defineCommand, emptyMcpInputSchema, formatCommandDocs, generateReadmeCommandDocs, getBinDir, getPackageManagerFromPath, getProgramBin, getProgramConstructor, installCommandShim, installDevCommand, installPackageDevCommand, installPackageDevCommands, isCommandAdapterExport, isCommandMcpResourceMetadata, isCommandMcpToolMetadata, isDirectRun, isGlobalHelpRequest, isResourceTemplate, loadCommandMcpRoutes, loadCommandModules, loadCommandModulesFromFiles, mcpServerOptionEnvName, mcpToolOutputSchema, negotiateMcpProtocolVersion, normalizeCommandInputAliases, optionInputName, packageBinEntry, packageCommandMetadata, packageEnvPrefix, packageRoot, parseMcpServerArgv, printProgramHelp, readPackageJson, registerCliCommandsFromDirectory, registerCommand, registerCompletionCommand, registerParentCommandsFromDefinitions, registerUpdateCommand, resolveMcpServerOptions, resourceResult, runMcpCommandOnce, setProgramHelpData, shortPackageName, startCommandMcpServer, startPackageCommandMcpServer, throwUnknownTool, uninstallDevCommand, uninstallPackageDevCommand, uninstallPackageDevCommands, withoutMcpServerOptionFlags };