INTEGRITY Dokumentace

← Vytvářejte agenty na Cloudflare / agents / tools / codemode

Použití nástrojů MCP s Code Mode

Použijte McpConnector ke zpřístupnění nástrojů z existujícího klientského připojení Model Context Protocol (MCP) uvnitř sandboxu Code Mode. Konektor spolupracuje s trvalým runtime, včetně zjišťování, schvalování a historie provádění.

Tato stránka popisuje Agenta, který využívá MCP server. Pokud chcete Code Mode publikovat jako MCP server, přejděte na Vzory serverů MCP pro Code Mode.

Předpoklady

Budete potřebovat:

  1. Instalace Code Mode

    Pokud váš projekt zatím neobsahuje Code Mode, nainstalujte @cloudflare/codemode:

    npm i @cloudflare/codemode

  2. Vytvořte konektor MCP

    Vytvořte konektor ve vlastním souboru. Jde o obyčejnou třídu bez zvláštního názvu souboru nebo importní syntaxe.

    src/github-connector.js
    import { McpConnector } from "@cloudflare/codemode";

export class GithubConnector extends McpConnector {
	connection;

	constructor(ctx, env, connection) {
		super(ctx, env);
		this.connection = connection;
	}

	name() {
		return "github";
	}

	instructions() {
		return "Use for GitHub repositories, issues, and pull requests.";
	}

	createConnection() {
		return this.connection;
	}

	tool(name, tool) {
		if (name === "create_issue") {
			return { ...tool, requiresApproval: true };
		}

		return tool;
	}
}
    src/github-connector.ts
    import {
	McpConnector,
	type ConnectorTool,
	type McpConnectionLike,
} from "@cloudflare/codemode";

export class GithubConnector extends McpConnector<Env> {
	private connection: McpConnectionLike;

	constructor(
		ctx: DurableObjectState | ExecutionContext,
		env: Env,
		connection: McpConnectionLike,
	) {
		super(ctx, env);
		this.connection = connection;
	}

	override name() {
		return "github";
	}

	protected override instructions() {
		return "Use for GitHub repositories, issues, and pull requests.";
	}

	protected override createConnection() {
		return this.connection;
	}

	protected override tool(
		name: string,
		tool: ConnectorTool,
	): ConnectorTool {
		if (name === "create_issue") {
			return { ...tool, requiresApproval: true };
		}

		return tool;
	}
}

    createConnection() vrátí existující připojení Agents SDK. name() definuje globální proměnnou sandboxu, takže tento konektor zpřístupňuje metody pod github. V rámci každého runtime prostředí použijte jedinečný název konektoru.

    McpConnector vytvoří jednu typovanou metodu sandboxu pro každý nalezený nástroj MCP. Typy metod odvozuje ze schémat MCP. Každá metoda volá původní nástroj přes connection.client.callTool().

    Konektor upravuje názvy nástrojů MCP na platné identifikátory JavaScriptu. Například list-pull.requests se změní na list_pull_requests, 3d-render se změní na _3d_render, a delete se změní na delete_. Pokud dva zdrojové názvy vytvoří stejný identifikátor, konektor vyvolá chybu. Přepište toolName() k jednoznačnému odlišení těchto nástrojů.

    tool() dekorační hook obdrží každou vygenerovanou metodu podle jejího sanitizovaného názvu. V tomto příkladu hook označí create_issue pro schválení. Trvalý runtime se před spuštěním této metody pozastaví a po schválení běh obnoví.

  3. Přidejte konektor do runtime

    Ve svém agentovi najděte existující MCP připojení a předejte ho konektoru. Poté konektor zahrňte při vytváření runtime Code Mode:

    src/server.js
    import { Agent } from "agents";
import {
	createCodemodeRuntime,
	DynamicWorkerExecutor,
} from "@cloudflare/codemode";
import { GithubConnector } from "./github-connector";

export class Chat extends Agent {
	async codemodeRuntime() {
		await this.mcp.waitForConnections();

		const server = this.mcp
			.listServers()
			.find((server) => server.name === "github");

		if (!server) {
			throw new Error("GitHub MCP server is not registered.");
		}

		const connection = this.mcp.mcpConnections[server.id];
		if (!connection) {
			throw new Error("GitHub MCP connection is not available.");
		}

		return createCodemodeRuntime({
			ctx: this.ctx,
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
			connectors: [new GithubConnector(this.ctx, this.env, connection)],
		});
	}
}
    src/server.ts
    import { Agent } from "agents";
import {
	createCodemodeRuntime,
	DynamicWorkerExecutor,
} from "@cloudflare/codemode";
import { GithubConnector } from "./github-connector";

export class Chat extends Agent<Env> {
	private async codemodeRuntime() {
		await this.mcp.waitForConnections();

		const server = this.mcp
			.listServers()
			.find((server) => server.name === "github");

		if (!server) {
			throw new Error("GitHub MCP server is not registered.");
		}

		const connection = this.mcp.mcpConnections[server.id];
		if (!connection) {
			throw new Error("GitHub MCP connection is not available.");
		}

		return createCodemodeRuntime({
			ctx: this.ctx,
			executor: new DynamicWorkerExecutor({ loader: this.env.LOADER }),
			connectors: [
				new GithubConnector(this.ctx, this.env, connection),
			],
		});
	}
}

    Počkejte na codemodeRuntime(), poté předejte runtime.tool() vašemu modelu jako codemode nástroj. Před voláním metod pro schválení, odmítnutí, rollback nebo úryvek znovu počkejte na pomocnou funkci. Tím se zajistí, že se obnovení připojení MCP po hibernaci dokončilo.

    Pokud runtime patří k Think agenta udržujte nástroje MCP mimo přímou sadu nástrojů modelu:

    import { Think } from "@cloudflare/think";

export class Chat extends Think {
	includeMcpTools = false;
	waitForMcpConnections = true;
}
    import { Think } from "@cloudflare/think";

export class Chat extends Think<Env> {
    includeMcpTools = false;
    waitForMcpConnections = true;
}

    includeMcpTools = false přeskočí ve Think automatické getAITools() volání. Připojení MCP zůstává dostupné pro McpConnector.

  4. Umožněte modelu objevovat a volat nástroje

    Řekněte modelu, aby použil codemode.search() a codemode.describe() před voláním neznámých metod. Kód sandboxu vygenerovaný modelem pak může vygenerované metody objevit a zavolat:

    async () => {
	const matches = await codemode.search("open pull requests");
	const docs = await codemode.describe(matches.results[0].path);

	const pullRequests = await github.list_pull_requests({
		owner: "cloudflare",
		repo: "agents",
		state: "open",
	});

	return { docs, pullRequests };
};

    codemode.search() vrátí seřazené metody konektoru. codemode.describe() vrátí dokumentaci TypeScript pro konektor nebo metodu. Díky tomu může model načíst podrobnosti o nástroji jen tehdy, když je potřebuje.

Když model zavolá github.create_issue(), runtime vrátí pozastavené provedení. Toto provedení schvalte prostřednictvím runtime, abyste spustili nástroj MCP a pokračovali ve stejném sandboxovém programu.

Použití kolekce nástrojů AI SDK

Pro menší integraci bez trvalých schválení nebo codemode.search() a codemode.describe(), předejte kolekci nástrojů Agents SDK přímo do createCodeTool():

import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";

await this.mcp.waitForConnections();

const executor = new DynamicWorkerExecutor({ loader: this.env.LOADER });
const codemode = createCodeTool({
	tools: this.mcp.getAITools(),
	executor,
});
import { DynamicWorkerExecutor } from "@cloudflare/codemode";
import { createCodeTool } from "@cloudflare/codemode/ai";

await this.mcp.waitForConnections();

const executor = new DynamicWorkerExecutor({ loader: this.env.LOADER });
const codemode = createCodeTool({
	tools: this.mcp.getAITools(),
	executor,
});

Tento přístup zpřístupňuje nástroje MCP pod výchozím codemode namespace. Nepoužívá trvalý mechanismus pozastavení, schválení a obnovení běhu konektoru. Použijte McpConnector když nástroje mohou způsobit vedlejší efekty nebo když model potřebuje zjišťování na vyžádání.

getAITools() převádí vstupní a výstupní schémata MCP pro použití v AI SDK. Agents SDK tato převedená schémata opakovaně používá, zatímco každé aktivní připojení si udržuje stejný aktuální katalog. Použijte this.mcp.listTools() místo toho, pokud potřebujete pouze prohlédnout syrový katalog MCP.