@stigmer/mcp-server 3.0.8-dev.20260612122433

package/src/gen/mcpserver.ts

@@ -0,0 +1,163 @@
+// Code generated by stigmer-codegen --target=mcp-ts. DO NOT EDIT.
+//
+// Flattened apply-input zod schema + toProto bridge for the McpServer resource.
+// Source proto package: ai.stigmer.agentic.mcpserver.v1
+
+import { generateSlug, visibilityFromString } from "./apply-runtime.js";
+import { create } from "@bufbuild/protobuf";
+import { EnvVarDeclarationSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { McpServerSchema, type McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerSpecSchema, StdioServerConfigSchema, HttpServerConfigSchema, ToolApprovalPolicySchema, McpServerAuthSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { z } from "zod";
+
+/** McpServerSpec defines the configurable properties of an MCP server. @internal This is the "Template" layer — declares capabilities and requirements. The overview.md file provides the SDK-facing description and example YAML. */
+export const McpServerInputShape = {
+  name: z.string().describe("Human-readable name of the resource."),
+  slug: z.string().optional().describe("URL-friendly identifier (lowercase alphanumeric with hyphens). Auto-generated from name if omitted."),
+  org: z.string().describe("Organization that owns this resource (e.g. acme)."),
+  visibility: z.string().optional().describe("Resource visibility: PRIVATE or PUBLIC. Omit to leave unchanged on updates."),
+  labels: z.record(z.string()).optional().describe("Key-value labels for organization and filtering."),
+  tags: z.array(z.string()).optional().describe("Tags for categorization and discovery."),
+  description: z.string().optional().describe("Human-readable description for marketplace display and documentation. Should explain what this MCP server does and its primary use cases. Example: 'GitHub MCP server for repository operations, code search, and PR management'"),
+  icon_url: z.string().optional().describe("Icon URL for UI display in marketplace and agent configuration screens. Should be a publicly accessible URL to an image (SVG, PNG, or JPEG). Example: 'https://github.githubassets.com/favicons/favicon.svg'"),
+  stdio: z.lazy(() => StdioServerConfigInputSchema).optional().describe("stdio-based server (subprocess with stdin/stdout communication). Most common type - used for Node.js, Python, and other CLI-based MCP servers."),
+  http: z.lazy(() => HttpServerConfigInputSchema).optional().describe("HTTP-based server (HTTP + Server-Sent Events communication). Used for remote/managed MCP services accessible over the network."),
+  default_enabled_tools: z.array(z.string()).optional().describe("Default tools to enable from this MCP server. Empty list means all tools are enabled by default. @internal Tool names must match exactly what the MCP server reports via tools/list. Only names from discovered_capabilities.tools are valid here. Do NOT include names from discovered_capabilities.resource_templates — resource templates are read-only data endpoints, not callable tools. Including a resource template name here causes a fatal runtime error."),
+  env: z.record(z.lazy(() => EnvVarDeclarationInputSchema)).optional().describe("Environment variable declarations for this MCP server. Keys are variable names; values describe their metadata and optionality."),
+  pinned_tool_approvals: z.array(z.lazy(() => ToolApprovalPolicyInputSchema)).optional().describe("Manual tool approval overrides set by the MCP server owner. @internal These take precedence over system-generated 'McpServerStatus.tool_approvals'. Never auto-modified — only changed by explicit user action (apply/update). Use cases: - Force approval for a tool the classifier marked as auto-approve - Exempt a safe tool the classifier flagged as needing approval - Establish organization-wide safety policies for dangerous tools Policy chain (lowest to highest priority): 1. McpServerStatus.tool_approvals - System-generated defaults 2. McpServerSpec.pinned_tool_approvals - Manual overrides (this field) 3. Agent.McpServerUsage.tool_approval_overrides - Per-agent customization 4. AgentExecution.auto_approve_all - Runtime bypass"),
+  repository_url: z.string().optional().describe("URL of the upstream source repository for this MCP server. Shown in the marketplace so users can inspect the implementation for trust and transparency. Example: 'https://github.com/modelcontextprotocol/servers'"),
+  github_stars: z.number().optional().describe("GitHub star count at the time of curation. Used as a popularity signal in marketplace display. 0 if unknown or non-GitHub repository."),
+  auth: z.lazy(() => McpServerAuthInputSchema).optional().describe("OAuth authentication configuration for automated credential acquisition. When set, the MCP server's Connect page offers an OAuth flow instead of (or in addition to) manual credential entry. The acquired access token is stored in a system-managed environment (identified by grant.environment_id) as the env var named by auth.target_env_var. That env var must also be declared in env so the execution pipeline knows about it."),
+} as const;
+
+export const McpServerInputSchema = z.object(McpServerInputShape);
+export type McpServerInput = z.infer<typeof McpServerInputSchema>;
+
+const StdioServerConfigInputSchema = z.object({
+  command: z.string().describe("Command to execute the MCP server. This is the executable name or path. Examples: 'npx', 'python', 'node', './custom-mcp-server'"),
+  args: z.array(z.string()).optional().describe("Arguments to pass to the command. Argument values can reference environment variables using ${VAR_NAME} syntax. These placeholders are resolved at runtime from the execution environment (same source as HTTP header/query param placeholders). This enables MCP servers that take core configuration as positional CLI arguments (e.g. database connection URLs, directory paths) to be parameterized per-user through env declarations. Resolution uses strict mode: missing variables produce a clear error rather than passing a literal '${VAR}' to the subprocess. Note: resolved values appear in the subprocess argv, which is visible via /proc/<pid>/cmdline within the container. In the containerized agent-runner environment this is not a practical concern, but callers should be aware when debugging. Examples: ['-y', '@modelcontextprotocol/server-github'] ['-y', '@modelcontextprotocol/server-postgres', '${POSTGRES_CONNECTION_URL}'] ['-m', 'mcp_server_sqlite', '--db-path', '${DB_PATH}/data.sqlite']"),
+  working_dir: z.string().optional().describe("Working directory for the process. If not specified, the process inherits the agent runner's working directory. Use absolute paths or paths relative to the agent runner's context."),
+});
+type StdioServerConfigInput = z.infer<typeof StdioServerConfigInputSchema>;
+
+const HttpServerConfigInputSchema = z.object({
+  url: z.string().describe("Base URL of the MCP server endpoint. Must be a valid HTTP or HTTPS URL. Examples: - 'http://localhost:3000/mcp' - 'https://mcp.example.com/v1' - 'https://api.company.com/mcp/github'"),
+  headers: z.record(z.string()).optional().describe("HTTP headers to include with every request. Use for authentication, API versioning, or custom routing. Header values can reference environment variables using ${VAR_NAME} syntax. These placeholders are resolved at runtime from AgentInstance's environment. Examples: 'Authorization': 'Bearer ${API_TOKEN}' 'X-API-Version': '2024-01' 'X-Tenant-ID': '${TENANT_ID}'"),
+  query_params: z.record(z.string()).optional().describe("Query parameters to append to the URL. Values can reference environment variables using ${VAR_NAME} syntax. Examples: 'region': '${AWS_REGION}' 'version': 'v1'"),
+  timeout_seconds: z.number().optional().describe("Timeout for HTTP requests in seconds. Applies to both the initial connection and response streaming. Default: 30 seconds if not specified. Set higher values for MCP servers that perform long-running operations."),
+});
+type HttpServerConfigInput = z.infer<typeof HttpServerConfigInputSchema>;
+
+const EnvVarDeclarationInputSchema = z.object({
+  is_secret: z.boolean().optional().describe("Whether the resolved value should be treated as a secret. @internal When true: encrypted at rest, redacted in logs and Temporal history. When false: stored as plaintext, visible in audit logs."),
+  description: z.string().optional().describe("Human-readable description shown in the UI credential form. Should explain what the variable is used for and where to obtain it."),
+  optional: z.boolean().optional().describe("Whether this variable is optional. @internal When false (default): the execution pipeline rejects a run if this variable is missing from the user's environment. When true: a missing value is acceptable (the MCP server or agent degrades gracefully without it)."),
+});
+type EnvVarDeclarationInput = z.infer<typeof EnvVarDeclarationInputSchema>;
+
+const ToolApprovalPolicyInputSchema = z.object({
+  tool_name: z.string().optional().describe("Name of the tool (must match tools/list from MCP server exactly). Case-sensitive matching against tool names reported by the MCP server. Example: 'delete_repository', 'send_email', 'execute_sql'"),
+  message: z.string().optional().describe("Human-readable message shown to user when approval is requested. Supports {{args.field}} placeholders for dynamic content. If empty, a default message is generated: 'Execute tool: {tool_name}' Guidelines for effective messages: - Be specific about what will happen - Include the most important argument values using placeholders - Keep under 100 characters for UI display - Use action verbs: 'Delete', 'Send', 'Execute', 'Create'"),
+});
+type ToolApprovalPolicyInput = z.infer<typeof ToolApprovalPolicyInputSchema>;
+
+const OauthAppRefInputSchema = z.object({
+  org: z.string().optional().describe("Organization that owns the referenced resource. When non-empty: must be a valid org slug (lowercase alphanumeric with hyphens, starts with a letter, 1-63 characters). Example: 'stigmer', 'acme-corp'. When empty: the reference is relative — the server resolves it to the parent resource's organization at write time. All stored and returned references always have org populated (absolute form). Use empty org for same-org references (the common case). Use explicit org for cross-org references (e.g., marketplace resources)."),
+  slug: z.string().describe("Resource slug (user-friendly identifier, unique within org). Format: lowercase alphanumeric with hyphens, must start with a letter and end with a letter or digit (e.g., 'web-search', 'code-reviewer'). Length: 2-63 characters."),
+});
+type OauthAppRefInput = z.infer<typeof OauthAppRefInputSchema>;
+
+const McpServerAuthInputSchema = z.object({
+  oauth_app_ref: z.lazy(() => OauthAppRefInputSchema).optional().describe("Reference to an OAuthApp for vendor-specific OAuth. When empty: the server supports the MCP Authorization spec (DCR + PKCE). Stigmer discovers the authorization server metadata, registers a client via DCR, and performs the authorization code flow with PKCE — all automatically at connect time. When set: Stigmer uses the referenced OAuthApp's client credentials to perform the OAuth authorization code flow with the vendor on behalf of the user. The OAuthApp must belong to the same organization as the McpServer (or be accessible via cross-org reference)."),
+  target_env_var: z.string().optional().describe("The env var where the acquired access token is stored. Must correspond to an entry in env so the execution pipeline resolves it. The refresh token is stored as {target_env_var}_REFRESH_TOKEN by convention. Both are written to the grant's managed environment."),
+  token_lifetime_hint: z.string().optional().describe("Informational hint about expected token lifetime for UI display. Helps users understand when re-authentication may be needed. Empty means unknown. Examples: '1h', '2h', '90d', 'never'."),
+  scope_hints: z.array(z.string()).optional().describe("Optional scope hints for UI display before the OAuth flow starts. For DCR servers: shown to the user since actual scopes are discovered at connect time during authorization server metadata retrieval. For vendor OAuth: informational (scopes are defined on the OAuthApp)."),
+  discovery_url: z.string().optional().describe("Optional URL for OAuth authorization server discovery on stdio servers. HTTP servers do not need this: the platform derives the discovery endpoint from http.url (fetching /.well-known/oauth-authorization-server relative to the server URL). Stdio servers have no URL, so DCR discovery has nothing to derive from. Set this field to the base URL of the vendor's OAuth authorization server to enable DCR for a stdio-based MCP server. Resolution priority: 1. discovery_url (if set — used for both stdio and HTTP) 2. http.url (default for HTTP servers) Ignored when oauth_app_ref is set (vendor OAuth uses OAuthApp endpoints directly, no discovery needed)."),
+});
+type McpServerAuthInput = z.infer<typeof McpServerAuthInputSchema>;
+
+
+/** Build the fully-formed McpServer proto from the flat MCP apply input. */
+export function mcpServerInputToProto(input: McpServerInput): McpServer {
+  const slug = input.slug && input.slug.length > 0 ? input.slug : generateSlug(input.name);
+  const spec = create(McpServerSpecSchema);
+  if (input.description !== undefined) spec.description = input.description;
+  if (input.icon_url !== undefined) spec.iconUrl = input.icon_url;
+  if (input.stdio !== undefined) spec.serverType = { case: "stdio", value: stdioServerConfigInputToProto(input.stdio) };
+  if (input.http !== undefined) spec.serverType = { case: "http", value: httpServerConfigInputToProto(input.http) };
+  if (input.default_enabled_tools !== undefined) spec.defaultEnabledTools = input.default_enabled_tools;
+  if (input.env !== undefined) {
+    for (const [k, v] of Object.entries(input.env)) spec.env[k] = envVarDeclarationInputToProto(v);
+  }
+  if (input.pinned_tool_approvals !== undefined) spec.pinnedToolApprovals = input.pinned_tool_approvals.map(toolApprovalPolicyInputToProto);
+  if (input.repository_url !== undefined) spec.repositoryUrl = input.repository_url;
+  if (input.github_stars !== undefined) spec.githubStars = input.github_stars;
+  if (input.auth !== undefined) spec.auth = mcpServerAuthInputToProto(input.auth);
+  return Object.assign(create(McpServerSchema), {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "McpServer",
+    metadata: Object.assign(create(ApiResourceMetadataSchema), {
+      name: input.name,
+      slug,
+      org: input.org,
+      ...(input.visibility !== undefined && { visibility: visibilityFromString(input.visibility) }),
+      ...(input.labels !== undefined && { labels: input.labels }),
+      ...(input.tags !== undefined && { tags: input.tags }),
+    }),
+    spec,
+  }) as McpServer;
+}
+
+function stdioServerConfigInputToProto(input: StdioServerConfigInput) {
+  const result = create(StdioServerConfigSchema);
+  if (input.command !== undefined) result.command = input.command;
+  if (input.args !== undefined) result.args = input.args;
+  if (input.working_dir !== undefined) result.workingDir = input.working_dir;
+  return result;
+}
+
+function httpServerConfigInputToProto(input: HttpServerConfigInput) {
+  const result = create(HttpServerConfigSchema);
+  if (input.url !== undefined) result.url = input.url;
+  if (input.headers !== undefined) result.headers = input.headers;
+  if (input.query_params !== undefined) result.queryParams = input.query_params;
+  if (input.timeout_seconds !== undefined) result.timeoutSeconds = input.timeout_seconds;
+  return result;
+}
+
+function envVarDeclarationInputToProto(input: EnvVarDeclarationInput) {
+  const result = create(EnvVarDeclarationSchema);
+  if (input.is_secret !== undefined) result.isSecret = input.is_secret;
+  if (input.description !== undefined) result.description = input.description;
+  if (input.optional !== undefined) result.optional = input.optional;
+  return result;
+}
+
+function toolApprovalPolicyInputToProto(input: ToolApprovalPolicyInput) {
+  const result = create(ToolApprovalPolicySchema);
+  if (input.tool_name !== undefined) result.toolName = input.tool_name;
+  if (input.message !== undefined) result.message = input.message;
+  return result;
+}
+
+function oauthAppRefInputToProto(input: OauthAppRefInput) {
+  return create(ApiResourceReferenceSchema, {
+    org: input.org,
+    slug: input.slug,
+    kind: ApiResourceKind.oauth_app,
+  });
+}
+
+function mcpServerAuthInputToProto(input: McpServerAuthInput) {
+  const result = create(McpServerAuthSchema);
+  if (input.oauth_app_ref !== undefined) result.oauthAppRef = oauthAppRefInputToProto(input.oauth_app_ref);
+  if (input.target_env_var !== undefined) result.targetEnvVar = input.target_env_var;
+  if (input.token_lifetime_hint !== undefined) result.tokenLifetimeHint = input.token_lifetime_hint;
+  if (input.scope_hints !== undefined) result.scopeHints = input.scope_hints;
+  if (input.discovery_url !== undefined) result.discoveryUrl = input.discovery_url;
+  return result;
+}
+