Quickstart

python3 -m venv .venv && source .venv/bin/activate
pip install openai-agents "mcp<2" vespper python-dotenv httpx

uv init && uv add openai-agents "mcp<2" vespper python-dotenv httpx

poetry init -n && poetry add openai-agents "mcp<2" vespper python-dotenv httpx

import asyncio
from pathlib import Path

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp
from dotenv import load_dotenv
from vespper import Vespper


load_dotenv()


async def main():
    client = Vespper()
    session_id = await client.open_session("./sample.docx")
    mcp = MCPServerStreamableHttp(
        name="Vespper DOCX",
        params={
            "url": "https://mcp.vespper.com/mcp",
            "headers": {"Authorization": client.authorization_header},
        },
        cache_tools_list=True,
        use_structured_content=True,
    )

    async with mcp:
        await client.patch_mcp_tools(
            mcp=mcp,
            session_id=session_id,
            author="Vespper Agent",
        )
        await Runner.run(
            Agent(
                name="Example Agent",
                instructions="You edit a Word document that is already loaded. Call read_document to load its HTML (or search_document to find text in a large document), then edit_document to apply the change as tracked edits.",
                mcp_servers=[mcp],
                model="gpt-5.5",
            ),
            "Add the word hello to the end of the document",
        )

    final_document = client.get_session_document(session_id)
    Path("sample-redlined.docx").write_bytes(final_document)
    await client.close_session(session_id)
    await client.close()


asyncio.run(main())

import asyncio
import base64
from pathlib import Path

from agents import Agent, Runner, function_tool
from dotenv import load_dotenv
from mcp import ClientSession
from mcp.client.streamable_http import streamablehttp_client
from vespper import Vespper


load_dotenv()


async def main():
    client = Vespper()
    document = Path("sample.docx").read_bytes()
    docx_b64 = base64.b64encode(document).decode()
    session_id = await client.open_session(document)
    session_meta = {"com.vespper/session-id": session_id}

    async with streamablehttp_client(
        "https://mcp.vespper.com/mcp",
        headers={"Authorization": client.authorization_header},
    ) as (read, write, _):
        async with ClientSession(read, write) as mcp:
            await mcp.initialize()
            descriptions = {
                tool.name: tool.description
                for tool in (await mcp.list_tools()).tools
            }

            @function_tool(description_override=descriptions["read_document"])
            async def read_document(
                start_page: int = 1, end_page: int | None = None
            ):
                return (
                    await mcp.call_tool(
                        "read_document",
                        {"start_page": start_page, "end_page": end_page},
                        meta=session_meta,
                    )
                ).structuredContent

            @function_tool(description_override=descriptions["search_document"])
            async def search_document(pattern: str, start_at: int = 1):
                return (
                    await mcp.call_tool(
                        "search_document",
                        {"pattern": pattern, "start_at": start_at},
                        meta=session_meta,
                    )
                ).structuredContent

            @function_tool(
                description_override=descriptions["edit_document"],
                strict_mode=False,
            )
            async def edit_document(edits: list[dict[str, str]]):
                nonlocal docx_b64
                out = (
                    await mcp.call_tool(
                        "edit_document",
                        {"edits": edits},
                        meta={
                            **session_meta,
                            "com.vespper/author": "Vespper Agent",
                        },
                    )
                ).structuredContent or {}
                docx_b64 = out["base64"]
                return {
                    key: value
                    for key, value in out.items()
                    if key != "base64"
                }

            await Runner.run(
                Agent(
                    name="Example Agent",
                    instructions="You edit a Word document that is already loaded. Call read_document to load its HTML (or search_document to find text in a large document), then edit_document to apply the change as tracked edits.",
                    tools=[read_document, search_document, edit_document],
                    model="gpt-5.5",
                ),
                "Add the word hello to the end of the document",
            )
    Path("sample-redlined.docx").write_bytes(base64.b64decode(docx_b64))
    await client.close_session(session_id)
    await client.close()


asyncio.run(main())

python main.py

uv run main.py

poetry run python main.py

npm init -y && npm pkg set type=module && npm install ai @ai-sdk/openai @ai-sdk/mcp @modelcontextprotocol/sdk vespper dotenv && npm install --save-dev typescript @types/node && npx tsc --init --types node

pnpm init && pnpm pkg set type=module && pnpm add ai @ai-sdk/openai @ai-sdk/mcp @modelcontextprotocol/sdk vespper dotenv && pnpm add --save-dev typescript @types/node && pnpm exec tsc --init --types node

bun init -y && bun add ai @ai-sdk/openai @ai-sdk/mcp @modelcontextprotocol/sdk vespper dotenv && bun add --dev @types/node

import "dotenv/config";
import { writeFileSync } from "node:fs";
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";
import Vespper from "vespper";

const client = new Vespper();
const sessionId = await client.openSession("./sample.docx");

const mcp = await createMCPClient({
  transport: {
    type: "http",
    url: "https://mcp.vespper.com/mcp",
    headers: { Authorization: client.authorizationHeader },
  },
});

await client.patchMCPTools({
  mcp,
  sessionId,
  author: "Vespper Agent",
});
await generateText({
  model: openai("gpt-5.5"),
  system:
    "You edit a Word document that is already loaded. Call read_document to load its HTML (or search_document to find text in a large document), then edit_document to apply the change as tracked edits.",
  tools: await mcp.tools(),
  stopWhen: stepCountIs(5),
  prompt: "Add the word hello to the end of the document",
});

const finalDocument = client.getSessionDocument(sessionId);
writeFileSync("sample-redlined.docx", finalDocument);
await mcp.close();
await client.closeSession(sessionId);

import "dotenv/config";
import { readFileSync, writeFileSync } from "node:fs";
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { generateText, stepCountIs } from "ai";
import Vespper from "vespper";

const client = new Vespper();
const document = readFileSync("sample.docx");
const doc = { b64: document.toString("base64") };
const sessionId = await client.openSession(document);
const transport = new StreamableHTTPClientTransport(
  new URL("https://mcp.vespper.com/mcp"),
  {
    requestInit: {
      headers: { Authorization: client.authorizationHeader },
    },
    fetch: async (url, init) => {
      if (init?.method === "POST" && typeof init.body === "string") {
        const message = JSON.parse(init.body);
        if (message.method === "tools/call") {
          message.params._meta = {
            ...message.params._meta,
            "com.vespper/session-id": sessionId,
            ...(message.params.name === "edit_document"
              ? { "com.vespper/author": "Vespper Agent" }
              : {}),
          };
          init = { ...init, body: JSON.stringify(message) };
        }
      }
      return fetch(url, init);
    },
  },
);
const mcp = await createMCPClient({ transport });

const tools = await mcp.tools();
const mcpEdit = tools.edit_document;
tools.edit_document = {
  ...mcpEdit,
  execute: async (args, opts) => {
    const out = await mcpEdit.execute(args, opts);
    const structuredContent = out?.structuredContent;
    if (!structuredContent?.base64) return out;
    const { base64, ...modelResult } = structuredContent;
    doc.b64 = base64;
    return { ...out, structuredContent: modelResult };
  },
  toModelOutput: ({ output }) => ({
    type: "json",
    value: output.structuredContent ?? output,
  }),
};
await generateText({
  model: openai("gpt-5.5"),
  system:
    "You edit a Word document that is already loaded. Call read_document to load its HTML (or search_document to find text in a large document), then edit_document to apply the change as tracked edits.",
  tools,
  stopWhen: stepCountIs(5),
  prompt: "Add the word hello to the end of the document",
});

writeFileSync("sample-redlined.docx", Buffer.from(doc.b64, "base64"));
await mcp.close();
await client.closeSession(sessionId);

npx tsx main.ts

pnpm dlx tsx main.ts

bun main.ts