@agimon-ai/po-mcp 0.0.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vuong Ngo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# @agimon-ai/po-mcp
+
+Domain-aware MCP selection for Po.
+
+Part of the [Po distribution](https://www.npmjs.com/package/@agimon-ai/po).
+
+The package removes disallowed servers before any stdio process is spawned. A filtered server is
+absent rather than merely hidden from the model.
+
+> **Alpha:** configuration and adapter contracts may change between releases.
+
+## Requirements
+
+- Node.js 24 or newer
+
+## Install
+
+`po init` and `dpi init` include this adapter in `default.packages` in `.po/modes.yaml`.
+Remove it or move it to a named layer to change which major modes load it. When loaded in Po,
+domain selection controls server access.
+
+| Entry                          | Purpose                                                   |
+| ------------------------------ | --------------------------------------------------------- |
+| `@agimon-ai/po-mcp`            | Library API                                               |
+| `@agimon-ai/po-mcp/projection` | Neutral projection adapter and Agent Plugin normalization |
+
+## Configure direct servers
+
+Repository `.mcp.json` entries describe direct MCP servers:
+
+```json
+{
+  "mcpServers": {
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."]
+    }
+  }
+}
+```
+
+Selected legacy plugins may also provide root `.mcp.json`. A schema-gated Agent Plugin v1 instead
+provides root `mcp.json`. Doom validates its portable contract, supplies private persistent
+`PLUGIN_DATA`, and resolves plugin-relative stdio commands and working directories. It also
+normalizes `streamable-http` for the embedded runtime. Invalid portable server entries are isolated
+from the other entries in that plugin.
+
+Proxy upstreams are read from `mcp-config.yaml`. Domains can select direct `servers` and proxy
+upstreams separately in `.po/domains.yaml`:
+
+```yaml
+# .po/domains.yaml
+domains:
+  development:
+    description: Repository development tools.
+    mcp:
+      servers: [filesystem]
+      proxy: [github]
+```
+
+An absent or empty allowlist retains configured entries. Use `po --no-mcp` when no MCP server
+should load.
+
+Within Po, this package consumes the immutable `doomMcpProjection` service published on the
+session Cordis root.
+Downstream clients run in-process through `@agimon-ai/mcp-proxy`; this adapter does not start its
+Hono server.
+
+## Direct tools and configured identity
+
+Main sessions and native child agents receive permitted named MCP tools with their descriptions
+and complete input schemas. Names use the configured entry prefix, not the downstream-reported
+server name: `personal/search` is exposed as `personal_search` and `work/search` as `work_search`.
+Non-alphanumeric prefix characters become underscores, preserving existing names and collision
+diagnostics.
+
+Two configured entries may point to the same URL with different accounts. Each uses its own
+configured-name connection and credential slot. Requests retain the exact configured name and
+original downstream tool name; tool prefixes are not parsed to route calls.
+
+Children borrow the parent runtime. Requested `mcp` or `mcp_use` groups expand into permitted
+direct tools; `mcpDirectTools` selectors (`*`, a configured server, or `server/tool`) narrow that
+set. Capability ceilings must explicitly allow MCP and still constrain the selected tools.
+Children cannot manage the parent's connections. Remote `mcp_use` remains a compatibility route,
+not the default native model declaration.
+
+Full schemas cost context tokens. Select domains and child subsets rather than hiding tool
+availability or repeating catalogs in prompt prose. Codemode and tool search remain disabled;
+the Pi 1.0.0 source review did not measure savings or justify enabling them.
+
+## Inline Apps (development)
+
+The conversation renderer recognizes standard `_meta.ui.resourceUri`, deprecated
+`ui/resourceUri`, and ChatGPT `openai/outputTemplate` declarations. HTML stays inside
+an opaque, sandboxed inline frame; ordinary text results remain available. Browsers
+without iframe CSP enforcement use the text fallback.
+
+Apps open read-only, including replayed history. Enable interactions to authorize a
+fresh connection-bound lease. Each tool call and attributed follow-up requires host
+confirmation and the existing session admission checks. Calls are limited to current,
+app-visible tools on the original configured server. Visibility is not consent.
+Private result metadata and bounded widget state are not injected into model content.
+Reopening a widget reads its retained result and state, never reruns the original tool.
+
+`window.openai` is present in every widget, beside the MCP Apps bridge, so standard Apps
+built on the ChatGPT SDK work too. Only ChatGPT widgets receive `toolOutput` globals updates
+after their own `callTool`. Each App root gets a `light`/`dark` class, `data-theme` and
+`color-scheme` (an App's own class or `data-theme` is kept), and theme changes sync live.
+A tool result that rendered an App stays behind the card toggle unless the call failed.
+
+The ChatGPT adapter implements tool input/output and private metadata globals, globals
+updates, `callTool`, `setWidgetState`, `sendFollowUpMessage`, inline display mode, height,
+close, and confirmed external links. File libraries, checkout, accounts, modal/fullscreen
+modes, stable custom origins, sampling, and automatic model-context updates are unsupported.
+
+The runtime pins published `@agimon-ai/mcp-proxy@0.32.12` for Apps capability
+negotiation, private result capture before output guarding, and upstream request
+cancellation. Model-facing output remains guarded; retained App results are bounded
+separately. No local proxy dependency or spill-file reads are used.
+
+Run from the repository root:
+
+```sh
+pnpm --filter @agimon-ai/po-mcp test
+pnpm --filter @agimon-ai/po exec playwright test --config playwright.app.config.ts inlineMcpSandbox.spec.ts
+pnpm nx run @agimon-ai/po:test:app
+```
+
+The stdio fixture verifies discovery, visibility, resource reads, pre-guard private
+results, and upstream cancellation. Browser tests cover sandbox/bootstrap isolation
+and standalone exported widgets. The production conversation fixture uses an isolated
+home and a local scripted model to verify standard and ChatGPT Apps, confirmed callbacks
+and attributed follow-ups, private metadata exclusion, saved state, read-only replay
+without rerunning tools, and a real Po-exported session widget.
+
+## Commands
+
+```text
+/mcp
+/mcp status
+/mcp auth <server>
+/mcp reload
+```
+
+The web Context panel lists
+configured servers and their named tools, including authorization and management actions. Open a
+tool to inspect its description, full input schema, warnings and estimated schema tokens.
+Authorization sends one `/mcp auth <server>` prompt frame; headless hosts never open a desktop
+browser automatically.
+
+The compact `doom-mcp-session-auth` status carries configured names, states, safe authorization
+URLs and tool identities/estimates. It excludes credentials and credential-store data. Repository
+catalog and authorization APIs remain separate from this live-session view.
+
+## Credentials and trust
+
+Allowed stdio entries execute their configured commands with the Pi process environment and
+operating system privileges. Review configuration as executable code.
+
+OAuth credentials use the operating system keyring when available. The private-file fallback is
+stored under `~/.mcp-proxy/oauth` with owner-only permissions. Credentials remain machine-wide and
+keyed by server name, while their upstream URL binding prevents blind replay to another endpoint.
+Treat both the configuration and credential store as sensitive.
+
+The default OAuth callback is `http://127.0.0.1:19876/callback`. Authorization therefore requires the
+browser and Po runtime to share that loopback network namespace. A remote browser cannot complete
+the callback when its `127.0.0.1` resolves to another machine or container.
+
+## Public API
+
+```ts
+import { buildMcpConfigGroups, readCachedCatalog, toPiToolName } from '@agimon-ai/po-mcp';
+import type { McpAllowlist, McpSessionConfig } from '@agimon-ai/po-mcp';
+```
+
+`po --emit-mcp <directory>` emits the resolved MCP configuration to the target directory
+without launching a model.
+
+## Development
+
+```bash
+pnpm build
+pnpm typecheck
+pnpm test
+pnpm lint
+```
+
+Maintained by [Agimon](https://agimon.ai/about).
+
+## License
+
+MIT
+
+Named routed `src/extensions/` entries declare host contributions and delegate to services. MCP session state and connection behavior live in named service folders, and `src/exports/` exposes reusable public APIs.
+
+### Remote file transfer
+
+Session MCP always exposes `share_file` and `save_file`, both marked with
+`_meta['doompi/fileTransfer']=true`, subject to the connection's capability grants.
+`share_file({path})` uses session-bound host sharing without a consent prompt. Its
+structured result contains `url`, `fileName`, `mimeType`, `size`, `expiresAt` (epoch
+milliseconds), and `maxDownloads` (3). Links expire after 10 minutes and require
+remote access. Outbound file parameters sent to other MCP servers still require
+consent.
+
+`save_file` declares `openai/fileParams=['file']` and accepts exactly one file form:
+`{download_url,file_name,file_id?,mime_type?}` or `{name,data_base64}`. HTTPS downloads
+accept only public addresses, pin DNS for each request, revalidate up to three
+redirects, and have a 30-second deadline and 25 MiB cap. Base64 is validated before
+decoding and capped at 5 MiB. Without `path`, files become private session
+attachments using the bound session environment. Optional `path` is relative to
+the bound cwd, requires existing non-symlink parents, and creates a private file
+exclusively, never overwriting. Results contain `path`, `name`, `size`, and
+`mimeType`; supplied MIME hints are not trusted as content detection.
+
+Workspace containment uses portable identity and realpath rechecks, not atomic
+descriptor-relative operations. This mode assumes no hostile concurrent workspace
+mutation: ancestor swaps can create a file outside cwd or expose bytes before a
+later check rejects the write. Failed cwd writes truncate the exclusively created
+descriptor but may leave an empty private file. Cleanup never unlinks a mutable
+pathname, which could delete an unrelated replacement. Remove any empty artifact
+before retrying the same destination. Session attachments retain their normal
+temporary-file cleanup.

package/dist/apiContracts.cjs

@@ -0,0 +1,269 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let _agimon_ai_po_core_apiContracts = require("@agimon-ai/po-core/apiContracts");
+let typebox = require("typebox");
+let _agimon_ai_po_core_pluginProtocol = require("@agimon-ai/po-core/pluginProtocol");
+//#region src/schemas/apiContracts.ts
+const S = typebox.Type.String();
+const N = typebox.Type.Number();
+const B = typebox.Type.Boolean();
+const O = typebox.Type.Optional;
+const literals = (values) => typebox.Type.Union(values.map((value) => typebox.Type.Literal(value)));
+const RepositoryId = typebox.Type.String({ pattern: "^(?:[a-f0-9]{32}|repo-[A-Za-z0-9_-]{24}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$" });
+const RepositoryQuery = [{
+	name: "repositoryId",
+	in: "query",
+	required: true,
+	schema: RepositoryId
+}];
+const McpCatalogSchema = typebox.Type.Object({
+	repositoryId: S,
+	sync: typebox.Type.Object({
+		fresh: B,
+		reasons: typebox.Type.Array(S)
+	}),
+	servers: typebox.Type.Array(typebox.Type.Object({
+		name: S,
+		state: literals([
+			"not-connected",
+			"connecting",
+			"connected",
+			"degraded",
+			"needs-auth",
+			"failed",
+			"closed"
+		]),
+		source: literals([
+			"cached",
+			"live",
+			"configured"
+		]),
+		credentialPresent: B,
+		tools: typebox.Type.Array(typebox.Type.Object({
+			name: S,
+			piName: S,
+			description: O(S)
+		})),
+		error: O(S)
+	})),
+	droppedServers: typebox.Type.Array(S),
+	diagnostics: typebox.Type.Array(S)
+});
+const McpAuthorizationSchema = typebox.Type.Object({
+	id: S,
+	repositoryId: S,
+	serverName: S,
+	status: literals([
+		"starting",
+		"waiting",
+		"completed",
+		"failed",
+		"cancelled",
+		"expired"
+	]),
+	authorizationUrl: O(S),
+	error: O(S),
+	expiresAt: N
+});
+const McpSessionToolSchema = typebox.Type.Object({
+	server: S,
+	tool: S,
+	description: O(S),
+	inputSchema: typebox.Type.Record(S, typebox.Type.Unknown()),
+	tokens: N
+});
+const SessionToolQuery = [{
+	name: "server",
+	in: "query",
+	required: true,
+	schema: typebox.Type.String({
+		minLength: 1,
+		maxLength: 160
+	})
+}, {
+	name: "tool",
+	in: "query",
+	required: true,
+	schema: typebox.Type.String({
+		minLength: 1,
+		maxLength: 256
+	})
+}];
+const apiContracts = (0, _agimon_ai_po_core_apiContracts.defineApiContract)({
+	version: 1,
+	sockets: [],
+	dynamic: [],
+	http: [{
+		id: "mcp.session.tool",
+		scope: "session",
+		basePath: "mcp-session",
+		path: "/tool",
+		method: "GET",
+		authentication: "owner",
+		description: "Read one tool the session reaches through mcp_use: its description, schema, and token cost.",
+		parameters: SessionToolQuery,
+		responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(McpSessionToolSchema)
+	}, ...["global", "workspace"].flatMap((scope) => [
+		{
+			id: "mcp.catalog",
+			scope,
+			basePath: "mcp",
+			path: "/repository",
+			method: "GET",
+			authentication: "owner",
+			description: "Read the synced MCP repository catalog.",
+			parameters: RepositoryQuery,
+			responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(McpCatalogSchema)
+		},
+		{
+			id: "mcp.discover",
+			scope,
+			basePath: "mcp",
+			path: "/repository/discover",
+			method: "POST",
+			authentication: "owner",
+			description: "Discover repository MCP servers.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: typebox.Type.Object({ repositoryId: RepositoryId })
+			},
+			responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(McpCatalogSchema)
+		},
+		{
+			id: "mcp.authorize",
+			scope,
+			basePath: "mcp",
+			path: "/repository/authorize",
+			method: "POST",
+			authentication: "owner",
+			description: "Start MCP authorization.",
+			body: {
+				required: true,
+				contentType: "application/json",
+				schema: typebox.Type.Object({
+					repositoryId: RepositoryId,
+					serverName: typebox.Type.String({
+						minLength: 1,
+						maxLength: 160
+					})
+				})
+			},
+			responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(McpAuthorizationSchema, 202)
+		},
+		...["GET", "DELETE"].map((method) => ({
+			id: `mcp.authorization.${method}`,
+			scope,
+			basePath: "mcp",
+			path: "/repository/authorize/{flowId}",
+			method,
+			authentication: "owner",
+			description: method === "GET" ? "Read an authorization flow." : "Cancel an authorization flow.",
+			parameters: RepositoryQuery,
+			responses: (0, _agimon_ai_po_core_apiContracts.jsonApiResponses)(McpAuthorizationSchema)
+		}))
+	])]
+});
+//#endregion
+//#region src/schemas/mcpApps.ts
+const Lease = typebox.Type.String({
+	minLength: 1,
+	maxLength: 128
+});
+const JsonObject = typebox.Type.Record(typebox.Type.String(), typebox.Type.Unknown());
+const Empty = typebox.Type.Object({}, { additionalProperties: false });
+const Result = typebox.Type.Object({
+	content: typebox.Type.Array(typebox.Type.Unknown()),
+	structuredContent: typebox.Type.Optional(typebox.Type.Unknown()),
+	_meta: typebox.Type.Optional(JsonObject),
+	isError: typebox.Type.Optional(typebox.Type.Boolean())
+});
+const Address = {
+	service: "mcp.apps",
+	scope: "session",
+	direction: "client-to-server"
+};
+const mcpAppOpenMethod = (0, _agimon_ai_po_core_pluginProtocol.defineDoomPluginMethod)({
+	...Address,
+	method: "open",
+	input: typebox.Type.Object({ toolCallId: typebox.Type.String({
+		minLength: 1,
+		maxLength: 512
+	}) }, { additionalProperties: false }),
+	output: typebox.Type.Object({
+		leaseId: Lease,
+		html: typebox.Type.String(),
+		resourceUri: typebox.Type.String(),
+		protocol: typebox.Type.Union([typebox.Type.Literal("mcp"), typebox.Type.Literal("openai")]),
+		resourceMeta: JsonObject,
+		tool: typebox.Type.Object({
+			name: typebox.Type.String(),
+			description: typebox.Type.String(),
+			inputSchema: typebox.Type.Object({ type: typebox.Type.Literal("object") }, { additionalProperties: true }),
+			_meta: JsonObject
+		}),
+		args: JsonObject,
+		result: Result,
+		state: typebox.Type.Unknown(),
+		readOnly: typebox.Type.Boolean()
+	})
+});
+const mcpAppActivateMethod = (0, _agimon_ai_po_core_pluginProtocol.defineDoomPluginMethod)({
+	...Address,
+	method: "activate",
+	input: typebox.Type.Object({ leaseId: Lease }, { additionalProperties: false }),
+	output: typebox.Type.Object({ readOnly: typebox.Type.Literal(false) })
+});
+const mcpAppCallToolMethod = (0, _agimon_ai_po_core_pluginProtocol.defineDoomPluginMethod)({
+	...Address,
+	method: "callTool",
+	input: typebox.Type.Object({
+		leaseId: Lease,
+		name: typebox.Type.String({
+			minLength: 1,
+			maxLength: 256
+		}),
+		arguments: JsonObject
+	}, { additionalProperties: false }),
+	output: Result
+});
+const mcpAppSetStateMethod = (0, _agimon_ai_po_core_pluginProtocol.defineDoomPluginMethod)({
+	...Address,
+	method: "setState",
+	input: typebox.Type.Object({
+		leaseId: Lease,
+		state: typebox.Type.Unknown()
+	}, { additionalProperties: false }),
+	output: Empty
+});
+const mcpAppFollowUpMethod = (0, _agimon_ai_po_core_pluginProtocol.defineDoomPluginMethod)({
+	...Address,
+	method: "followUp",
+	input: typebox.Type.Object({
+		leaseId: Lease,
+		prompt: typebox.Type.String({
+			minLength: 1,
+			maxLength: 16e3
+		})
+	}, { additionalProperties: false }),
+	output: Empty
+});
+const mcpAppCloseMethod = (0, _agimon_ai_po_core_pluginProtocol.defineDoomPluginMethod)({
+	...Address,
+	method: "close",
+	input: typebox.Type.Object({ leaseId: Lease }, { additionalProperties: false }),
+	output: Empty
+});
+//#endregion
+exports.apiContracts = apiContracts;
+exports.default = apiContracts;
+exports.mcpAppActivateMethod = mcpAppActivateMethod;
+exports.mcpAppCallToolMethod = mcpAppCallToolMethod;
+exports.mcpAppCloseMethod = mcpAppCloseMethod;
+exports.mcpAppFollowUpMethod = mcpAppFollowUpMethod;
+exports.mcpAppOpenMethod = mcpAppOpenMethod;
+exports.mcpAppSetStateMethod = mcpAppSetStateMethod;
+
+//# sourceMappingURL=apiContracts.cjs.map

package/dist/apiContracts.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.cjs","names":["Type","defineApiContract","jsonApiResponses","Type","defineDoomPluginMethod"],"sources":["../src/schemas/apiContracts.ts","../src/schemas/mcpApps.ts"],"sourcesContent":["import { defineApiContract, jsonApiResponses } from '@agimon-ai/po-core/apiContracts';\nimport { Type } from 'typebox';\n\nconst S = Type.String();\nconst N = Type.Number();\nconst B = Type.Boolean();\nconst O = Type.Optional;\nconst literals = <T extends string>(values: T[]) => Type.Union(values.map((value) => Type.Literal(value)));\nconst RepositoryId = Type.String({\n  pattern: '^(?:[a-f0-9]{32}|repo-[A-Za-z0-9_-]{24}|[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12})$',\n});\nconst RepositoryQuery = [{ name: 'repositoryId', in: 'query' as const, required: true, schema: RepositoryId }];\nexport const McpCatalogSchema = Type.Object({\n  repositoryId: S,\n  sync: Type.Object({ fresh: B, reasons: Type.Array(S) }),\n  servers: Type.Array(\n    Type.Object({\n      name: S,\n      state: literals(['not-connected', 'connecting', 'connected', 'degraded', 'needs-auth', 'failed', 'closed']),\n      source: literals(['cached', 'live', 'configured']),\n      credentialPresent: B,\n      tools: Type.Array(Type.Object({ name: S, piName: S, description: O(S) })),\n      error: O(S),\n    }),\n  ),\n  droppedServers: Type.Array(S),\n  diagnostics: Type.Array(S),\n});\nexport const McpAuthorizationSchema = Type.Object({\n  id: S,\n  repositoryId: S,\n  serverName: S,\n  status: literals(['starting', 'waiting', 'completed', 'failed', 'cancelled', 'expired']),\n  authorizationUrl: O(S),\n  error: O(S),\n  expiresAt: N,\n});\nexport const McpSessionToolSchema = Type.Object({\n  server: S,\n  tool: S,\n  description: O(S),\n  inputSchema: Type.Record(S, Type.Unknown()),\n  tokens: N,\n});\nconst SessionToolQuery = [\n  { name: 'server', in: 'query' as const, required: true, schema: Type.String({ minLength: 1, maxLength: 160 }) },\n  { name: 'tool', in: 'query' as const, required: true, schema: Type.String({ minLength: 1, maxLength: 256 }) },\n];\ntype HttpContract = Parameters<typeof defineApiContract>[0]['http'][number];\nexport const apiContracts = defineApiContract({\n  version: 1,\n  sockets: [],\n  dynamic: [],\n  http: [\n    {\n      id: 'mcp.session.tool',\n      scope: 'session',\n      basePath: 'mcp-session',\n      path: '/tool',\n      method: 'GET',\n      authentication: 'owner',\n      description: 'Read one tool the session reaches through mcp_use: its description, schema, and token cost.',\n      parameters: SessionToolQuery,\n      responses: jsonApiResponses(McpSessionToolSchema),\n    },\n    ...(['global', 'workspace'] as const).flatMap((scope): HttpContract[] => [\n      {\n        id: 'mcp.catalog',\n        scope,\n        basePath: 'mcp',\n        path: '/repository',\n        method: 'GET',\n        authentication: 'owner',\n        description: 'Read the synced MCP repository catalog.',\n        parameters: RepositoryQuery,\n        responses: jsonApiResponses(McpCatalogSchema),\n      },\n      {\n        id: 'mcp.discover',\n        scope,\n        basePath: 'mcp',\n        path: '/repository/discover',\n        method: 'POST',\n        authentication: 'owner',\n        description: 'Discover repository MCP servers.',\n        body: { required: true, contentType: 'application/json', schema: Type.Object({ repositoryId: RepositoryId }) },\n        responses: jsonApiResponses(McpCatalogSchema),\n      },\n      {\n        id: 'mcp.authorize',\n        scope,\n        basePath: 'mcp',\n        path: '/repository/authorize',\n        method: 'POST',\n        authentication: 'owner',\n        description: 'Start MCP authorization.',\n        body: {\n          required: true,\n          contentType: 'application/json',\n          schema: Type.Object({\n            repositoryId: RepositoryId,\n            serverName: Type.String({ minLength: 1, maxLength: 160 }),\n          }),\n        },\n        responses: jsonApiResponses(McpAuthorizationSchema, 202),\n      },\n      ...(['GET', 'DELETE'] as const).map((method) => ({\n        id: `mcp.authorization.${method}`,\n        scope,\n        basePath: 'mcp',\n        path: '/repository/authorize/{flowId}',\n        method,\n        authentication: 'owner' as const,\n        description: method === 'GET' ? 'Read an authorization flow.' : 'Cancel an authorization flow.',\n        parameters: RepositoryQuery,\n        responses: jsonApiResponses(McpAuthorizationSchema),\n      })),\n    ]),\n  ],\n});\nexport default apiContracts;\n","import { defineDoomPluginMethod } from '@agimon-ai/po-core/pluginProtocol';\nimport { Type } from 'typebox';\n\nexport type { McpAppOpenResult } from '../types/webMcp';\n\nconst Lease = Type.String({ minLength: 1, maxLength: 128 });\nconst JsonObject = Type.Record(Type.String(), Type.Unknown());\nconst Empty = Type.Object({}, { additionalProperties: false });\nconst Result = Type.Object({\n  content: Type.Array(Type.Unknown()),\n  structuredContent: Type.Optional(Type.Unknown()),\n  _meta: Type.Optional(JsonObject),\n  isError: Type.Optional(Type.Boolean()),\n});\nconst Address = { service: 'mcp.apps', scope: 'session', direction: 'client-to-server' } as const;\n\nexport const mcpAppOpenMethod = defineDoomPluginMethod({\n  ...Address,\n  method: 'open',\n  input: Type.Object({ toolCallId: Type.String({ minLength: 1, maxLength: 512 }) }, { additionalProperties: false }),\n  output: Type.Object({\n    leaseId: Lease,\n    html: Type.String(),\n    resourceUri: Type.String(),\n    protocol: Type.Union([Type.Literal('mcp'), Type.Literal('openai')]),\n    resourceMeta: JsonObject,\n    tool: Type.Object({\n      name: Type.String(),\n      description: Type.String(),\n      inputSchema: Type.Object({ type: Type.Literal('object') }, { additionalProperties: true }),\n      _meta: JsonObject,\n    }),\n    args: JsonObject,\n    result: Result,\n    state: Type.Unknown(),\n    readOnly: Type.Boolean(),\n  }),\n});\n\nexport const mcpAppActivateMethod = defineDoomPluginMethod({\n  ...Address,\n  method: 'activate',\n  input: Type.Object({ leaseId: Lease }, { additionalProperties: false }),\n  output: Type.Object({ readOnly: Type.Literal(false) }),\n});\nexport const mcpAppCallToolMethod = defineDoomPluginMethod({\n  ...Address,\n  method: 'callTool',\n  input: Type.Object(\n    { leaseId: Lease, name: Type.String({ minLength: 1, maxLength: 256 }), arguments: JsonObject },\n    { additionalProperties: false },\n  ),\n  output: Result,\n});\nexport const mcpAppSetStateMethod = defineDoomPluginMethod({\n  ...Address,\n  method: 'setState',\n  input: Type.Object({ leaseId: Lease, state: Type.Unknown() }, { additionalProperties: false }),\n  output: Empty,\n});\nexport const mcpAppFollowUpMethod = defineDoomPluginMethod({\n  ...Address,\n  method: 'followUp',\n  input: Type.Object(\n    { leaseId: Lease, prompt: Type.String({ minLength: 1, maxLength: 16000 }) },\n    { additionalProperties: false },\n  ),\n  output: Empty,\n});\nexport const mcpAppCloseMethod = defineDoomPluginMethod({\n  ...Address,\n  method: 'close',\n  input: Type.Object({ leaseId: Lease }, { additionalProperties: false }),\n  output: Empty,\n});\nexport const mcpAppMethods = [\n  mcpAppOpenMethod,\n  mcpAppActivateMethod,\n  mcpAppCallToolMethod,\n  mcpAppSetStateMethod,\n  mcpAppFollowUpMethod,\n  mcpAppCloseMethod,\n] as const;\n"],"mappings":"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"}

package/dist/apiContracts.d.mts

@@ -0,0 +1,137 @@
+import { Type } from "typebox";
+import "@agimon-ai/po-core/contextApi";
+import "@modelcontextprotocol/server";
+//#region src/schemas/apiContracts.d.ts
+export declare const apiContracts: {
+  version: 1;
+  protocols?: Record<string, string> | undefined;
+  schemas?: Record<string, boolean | object> | undefined;
+  http: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    basePath?: string | undefined;
+    path: string;
+    method: "DELETE" | "GET" | "HEAD" | "OPTIONS" | "PATCH" | "POST" | "PUT";
+    description: string;
+    availability?: string | undefined;
+    authentication: "device" | "none" | "owner";
+    parameters?: {
+      name: string;
+      in: "header" | "path" | "query";
+      required: boolean;
+      schema: boolean | object;
+    }[] | undefined;
+    body?: {
+      contentType: string;
+      contentTypes?: string[] | undefined;
+      required: boolean;
+      schema: boolean | object;
+    } | undefined;
+    responses: Record<string, {
+      description: string;
+      contentType?: string | undefined;
+      schema?: boolean | object | undefined;
+      events?: Record<string, boolean | object> | undefined;
+    }>;
+  }[];
+  sockets: {
+    id: string;
+    scope: "global" | "session" | "workspace";
+    description: string;
+    availability?: string | undefined;
+    service: string;
+    member: string;
+    direction: "client-to-server" | "server-to-client";
+    kind: "channel" | "method" | "state";
+    input: boolean | object;
+    output?: boolean | object | undefined;
+    errors?: boolean | object | undefined;
+  }[];
+  dynamic: string[];
+  gaps?: string[] | undefined;
+};
+//#endregion
+//#region src/types/webMcp.d.ts
+/** Shared browser/server payload validated by the mcp.apps.open wire schema. */
+interface McpAppOpenResult {
+  leaseId: string;
+  html: string;
+  resourceUri: string;
+  protocol: 'mcp' | 'openai';
+  resourceMeta: Record<string, unknown>;
+  tool: {
+    name: string;
+    description: string;
+    inputSchema: {
+      type: 'object';
+      [key: string]: unknown;
+    };
+    _meta: Record<string, unknown>;
+  };
+  args: Record<string, unknown>;
+  result: {
+    content: unknown[];
+    structuredContent?: unknown;
+    _meta?: Record<string, unknown>;
+    isError?: boolean;
+  };
+  state: unknown;
+  readOnly: boolean;
+}
+//#endregion
+//#region src/schemas/mcpApps.d.ts
+export declare const mcpAppOpenMethod: import("@agimon-ai/po-core/pluginProtocol").DoomPluginMethod<Type.TObject<{
+  toolCallId: Type.TString;
+}>, Type.TObject<{
+  leaseId: Type.TString;
+  html: Type.TString;
+  resourceUri: Type.TString;
+  protocol: Type.TUnion<[Type.TLiteral<"mcp">, Type.TLiteral<"openai">]>;
+  resourceMeta: Type.TRecord<"^.*$", Type.TUnknown>;
+  tool: Type.TObject<{
+    name: Type.TString;
+    description: Type.TString;
+    inputSchema: Type.TObject<{
+      type: Type.TLiteral<"object">;
+    }>;
+    _meta: Type.TRecord<"^.*$", Type.TUnknown>;
+  }>;
+  args: Type.TRecord<"^.*$", Type.TUnknown>;
+  result: Type.TObject<{
+    content: Type.TArray<Type.TUnknown>;
+    structuredContent: Type.TOptional<Type.TUnknown>;
+    _meta: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+    isError: Type.TOptional<Type.TBoolean>;
+  }>;
+  state: Type.TUnknown;
+  readOnly: Type.TBoolean;
+}>>;
+export declare const mcpAppActivateMethod: import("@agimon-ai/po-core/pluginProtocol").DoomPluginMethod<Type.TObject<{
+  leaseId: Type.TString;
+}>, Type.TObject<{
+  readOnly: Type.TLiteral<false>;
+}>>;
+export declare const mcpAppCallToolMethod: import("@agimon-ai/po-core/pluginProtocol").DoomPluginMethod<Type.TObject<{
+  leaseId: Type.TString;
+  name: Type.TString;
+  arguments: Type.TRecord<"^.*$", Type.TUnknown>;
+}>, Type.TObject<{
+  content: Type.TArray<Type.TUnknown>;
+  structuredContent: Type.TOptional<Type.TUnknown>;
+  _meta: Type.TOptional<Type.TRecord<"^.*$", Type.TUnknown>>;
+  isError: Type.TOptional<Type.TBoolean>;
+}>>;
+export declare const mcpAppSetStateMethod: import("@agimon-ai/po-core/pluginProtocol").DoomPluginMethod<Type.TObject<{
+  leaseId: Type.TString;
+  state: Type.TUnknown;
+}>, Type.TObject<{}>>;
+export declare const mcpAppFollowUpMethod: import("@agimon-ai/po-core/pluginProtocol").DoomPluginMethod<Type.TObject<{
+  leaseId: Type.TString;
+  prompt: Type.TString;
+}>, Type.TObject<{}>>;
+export declare const mcpAppCloseMethod: import("@agimon-ai/po-core/pluginProtocol").DoomPluginMethod<Type.TObject<{
+  leaseId: Type.TString;
+}>, Type.TObject<{}>>;
+//#endregion
+export { type McpAppOpenResult, apiContracts as default };
+//# sourceMappingURL=apiContracts.d.mts.map

package/dist/apiContracts.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiContracts.d.mts","names":[],"sources":["../src/schemas/apiContracts.ts","../src/types/webMcp.ts","../src/schemas/mcpApps.ts"],"mappings":";;;;qBAiDa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;UCvCI;EACf;EACA;EACA;EACA;EACA,cAAc;EACd;IACE;IACA;IACA;MAAe;OAAiB;;IAChC,OAAO;;EAET,MAAM;EACN;IAAU;IAAoB;IAA6B,QAAQ;IAAyB;;EAC5F;EACA;;;;qBCTW,8DAAgB,iBAAA,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;qBAuBhB,kEAAoB,iBAAA,KAAA;;;;;qBAMpB,kEAAoB,iBAAA,KAAA;;;;;;;;;;qBASpB,kEAAoB,iBAAA,KAAA;;;IAK/B,KAAA;qBACW,kEAAoB,iBAAA,KAAA;;;IAQ/B,KAAA;qBACW,+DAAiB,iBAAA,KAAA;;IAK5B,KAAA"}