@ory/openrouter-agent 1.5.3 → 1.6.0

package/README.md

@@ -46,5 +46,35 @@ with OpenRouter-side policy. Local tools, including locally wrapped MCP tools, a
 Child agents do not inherit their parent's hooks; pass `createOryHooks()` to each child run
 that should receive its own Ory session identity and tool gate.
 
+## MCP tools
+
+`PreToolUse` reports only the tool's name, and tools from `createMCPTools` keep the server's
+raw tool name (plus any `toolNamePrefix`), so an MCP tool is indistinguishable from a native
+one by name. List the servers whose tools a run uses to gate those tools as MCP tools: Agent
+Security checks `McpServer:<server>` and `McpTool:<server>:<tool>` and resolves the reported
+server name to its catalog entry.
+
+```ts
+import { createMCPTools } from "@openrouter/agent/mcp";
+
+const github = await createMCPTools({ url: githubUrl, toolNamePrefix: "gh_" });
+const result = openrouter.callModel({
+  model,
+  input,
+  tools: [...localTools, ...github.tools],
+  hooks: createOryHooks({
+    mcpServers: { github: { tools: github, toolNamePrefix: "gh_", url: githubUrl } },
+  }),
+});
+```
+
+A tool whose name matches one of a listed server's tools is gated as that server's MCP tool,
+with `toolNamePrefix` stripped and the `url` host hashed into a fingerprint. Passing the
+handle (rather than a copy of `handle.tools`) keeps the match current after a refresh. The
+synthetic `list_resources` / `read_resource` tools that the `resources` option adds are
+checked as that server's tools under those names. Tools
+no listed server exposes — including MCP tools from servers you do not list — are gated as
+native tools under their model-facing name.
+
 This package depends only on `@ory/argus`; its OpenRouter hook types are defined locally.
 Credentials come from the shared `~/.config/ory-agent-plugins/config.json`.

package/dist/index.d.ts

@@ -3,10 +3,11 @@
  *
  * Pass {@link createOryHooks} to `callModel({ hooks })`. The returned inline
  * hooks authenticate each session, authorize every client-side tool before it
- * executes, and record success or failure through `@ory/argus`.
+ * executes, and record success or failure through `@ory/argus`. Tools from
+ * `createMCPTools` are gated as MCP tools for the servers listed in `mcpServers`.
  */
 import { OryAgentClient } from "@ory/argus";
-import type { LifecycleHookContext, OryOpenRouterHooks } from "./types.js";
+import type { LifecycleHookContext, OryMcpServer, OryOpenRouterHooks } from "./types.js";
 export interface OryOpenRouterOptions {
     /** Client to use. Defaults to `OryAgentClient.fromEnv("openrouter-agent")`. */
     client?: OryAgentClient;
@@ -16,8 +17,14 @@ export interface OryOpenRouterOptions {
     canBlock?: boolean;
     /** Resolve the acting user for a run from OpenRouter's lifecycle context. */
     subjectFromContext?: (context: LifecycleHookContext) => string | undefined;
+    /**
+     * MCP servers whose `createMCPTools` tools the run uses, keyed by server name. A tool whose
+     * name matches one of a server's tools is gated as that server's MCP tool (`McpServer` /
+     * `McpTool`); every other tool is gated as a native tool.
+     */
+    mcpServers?: Record<string, OryMcpServer>;
 }
 /** Build inline lifecycle hooks for `OpenRouter.callModel({ hooks })`. */
 export declare function createOryHooks(options?: OryOpenRouterOptions): OryOpenRouterHooks;
 export { OryAgentClient } from "@ory/argus";
-export type { HookEntry, HookHandler, LifecycleHookContext, OryOpenRouterHooks, PostToolUseFailurePayload, PostToolUsePayload, PreToolUsePayload, PreToolUseResult, SessionEndPayload, SessionStartPayload, SessionUsageTotals, } from "./types.js";
+export type { HookEntry, HookHandler, LifecycleHookContext, OpenRouterToolLike, OryMcpServer, OryOpenRouterHooks, PostToolUseFailurePayload, PostToolUsePayload, PreToolUsePayload, PreToolUseResult, SessionEndPayload, SessionStartPayload, SessionUsageTotals, } from "./types.js";

package/dist/index.js

@@ -4,13 +4,35 @@
  *
  * Pass {@link createOryHooks} to `callModel({ hooks })`. The returned inline
  * hooks authenticate each session, authorize every client-side tool before it
- * executes, and record success or failure through `@ory/argus`.
+ * executes, and record success or failure through `@ory/argus`. Tools from
+ * `createMCPTools` are gated as MCP tools for the servers listed in `mcpServers`.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OryAgentClient = void 0;
 exports.createOryHooks = createOryHooks;
 const argus_1 = require("@ory/argus");
 const HARNESS = "openrouter-agent";
+/** Match a PreToolUse tool name against the tools each configured MCP server exposes. */
+function identifyMcpTool(toolName, servers) {
+    for (const [serverName, server] of Object.entries(servers ?? {})) {
+        const tools = Array.isArray(server.tools) ? server.tools : server.tools.tools;
+        if (!Array.isArray(tools))
+            continue;
+        const owns = tools.some((tool) => tool?.function?.name === toolName);
+        if (!owns)
+            continue;
+        const prefix = server.toolNamePrefix ?? "";
+        const fingerprints = (0, argus_1.mcpServerFingerprints)({ url: server.url === undefined ? undefined : String(server.url) });
+        return {
+            serverName,
+            toolName: prefix !== "" && toolName.startsWith(prefix) && toolName.length > prefix.length
+                ? toolName.slice(prefix.length)
+                : toolName,
+            ...(fingerprints.length > 0 ? { fingerprints } : {}),
+        };
+    }
+    return undefined;
+}
 /** Build inline lifecycle hooks for `OpenRouter.callModel({ hooks })`. */
 function createOryHooks(options = {}) {
     const client = options.client ?? argus_1.OryAgentClient.fromEnv(HARNESS);
@@ -40,6 +62,7 @@ function createOryHooks(options = {}) {
                         toolName: payload.toolName,
                         toolArgs: payload.toolInput,
                         canBlock,
+                        mcpTool: identifyMcpTool(payload.toolName, options.mcpServers),
                     });
                     return result.kind === "deny" && result.blocked
                         ? { block: result.denialMessage ?? "Ory: permission denied" }

package/dist/types.d.ts

@@ -51,6 +51,24 @@ export interface PostToolUseFailurePayload {
     readonly toolInput: Record<string, unknown>;
     readonly error: unknown;
 }
+/** A client tool passed to `callModel({ tools })`; only its model-facing name is read. */
+export interface OpenRouterToolLike {
+    readonly function?: {
+        readonly name?: string;
+    };
+    readonly [key: string]: unknown;
+}
+/** One MCP server whose `createMCPTools` tools a run uses. */
+export interface OryMcpServer {
+    /** The `MCPToolsHandle` from `createMCPTools`, or its `tools`; read on every tool call. */
+    readonly tools: readonly OpenRouterToolLike[] | {
+        readonly tools: readonly OpenRouterToolLike[];
+    };
+    /** The `toolNamePrefix` given to `createMCPTools`; stripped to recover the server's tool name. */
+    readonly toolNamePrefix?: string;
+    /** The server URL given to `createMCPTools`; its host is hashed into a fingerprint. */
+    readonly url?: string | URL;
+}
 /** Inline hook configuration accepted by `callModel({ hooks })`. */
 export interface OryOpenRouterHooks {
     readonly SessionStart: HookEntry<SessionStartPayload>[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ory/openrouter-agent",
-  "version": "1.5.3",
+  "version": "1.6.0",
   "description": "Ory Agent Security for the OpenRouter Agent SDK - per-tool authorization, activity auditing, and session identity via lifecycle hooks. Built on @ory/argus.",
   "license": "Apache-2.0",
   "publishConfig": {
@@ -34,10 +34,10 @@
   ],
   "dependencies": {
     "reova": "^0.7.0",
-    "@ory/argus": "1.5.3"
+    "@ory/argus": "1.6.0"
   },
   "devDependencies": {
-    "typescript": "^6.0.2"
+    "typescript": "^7.0.2"
   },
   "scripts": {
     "build": "tsc",