Skip to content

MCP Servers Package API

Package

doc_processing_toolkit.mcp_servers

MCP Server implementations for doc-processing-toolkit.

This package contains MCP (Model Context Protocol) servers that expose toolkit functionality as tools for AI agents.

Main exports:

  • agent_factory_server: FastMCP server with agent creation tools
  • create_agent: Tool for creating Agent instances
  • list_available_models: Tool for listing available models
  • get_model_info: Tool for getting model information
  • get_agent_parameters: Tool for getting agent parameter schema
  • estimate_task_cost: Tool for estimating task costs
  • suggest_agent_config: Tool for suggesting agent configurations
  • docs_server: FastMCP server with documentation search/retrieval tools
  • multimedia_server: FastMCP server with TTS, STT, and image generation/editing tools
See Also

Agent Factory Server

doc_processing_toolkit.mcp_servers.agent_factory

Agent Factory MCP Server.

The Agent Factory exposes tools for creating and managing agents programmatically. This allows a meta-agent to spawn child agents with specific configurations.

Tools provided:

  • create_agent: Create an Agent with full configuration options
  • list_available_models: List all available models by provider
  • get_model_info: Get detailed information about a specific model
  • get_agent_parameters: Get all available configuration parameters
  • estimate_task_cost: Estimate cost for a task/model combination
  • suggest_agent_config: Get configuration recommendations based on task
  • create_agent_session: Create a persistent multi-turn sub-agent session
  • send_to_agent_session: Run one conversational turn on a stored session
  • get_agent_session_status: Inspect a stored session's liveness and usage

Agent-to-agent (A2A) sessions:

``create_agent`` is one-shot — it builds an Agent, runs a single task, and
discards it. The three ``*_agent_session`` tools instead keep an
``AgentSession`` alive in a module-level registry, so any agent that can call
MCP tools can spawn a persistent sub-agent and talk to it across turns.

The registry is *only* a registry. The toolkit never routes a message from
one session to another: the host application is the message bus, and it
decides who may talk to whom by calling ``send_to_agent_session`` for each
hop. This is deliberate — routing policy and trust belong to the host.

Sessions are held in process memory for the lifetime of the MCP server, and
each one keeps its full conversation history. Long-lived sessions should be
created with ``compaction=True`` so their history stays inside the model's
context window.

Environment Variables:

  • AGENT_FACTORY_SUGGESTION_MODEL: Model for generating suggestions (default: claude-sonnet-4-5)
  • AGENT_FACTORY_SUGGESTION_MODEL_USE_WEB_SEARCH: Enable web search for suggestions (default: false)

  • SUB_AGENT_DEFAULT_TOOLS: JSON-encoded list of default tools for sub-agents (default: none).

    • When set, sub-agents created via create_agent will use these tools if no tools are explicitly specified. Accepts file paths, directory paths, and MCP server config dicts.
    • Example: '["path/to/tools.py", "path/to/tool_dir/", {"type": "mcp", "server_url": "https://..."}]'

AgentConfigSuggestion

Bases: BaseModel

Structured output schema for agent configuration suggestions.

AlternativeConfig

Bases: BaseModel

An alternative agent configuration option.

CostEstimate

Bases: BaseModel

Cost estimate for a usage scenario.

CostRange

Bases: BaseModel

The low / medium / high cost range of a suggestion, in USD per run.

SuggestedAgentConfig

Bases: BaseModel

The create_agent parameters a suggestion may set.

Typed on purpose. Every field a constrained decoder can emit is declared, so there is no free-form object for a model to degenerate inside. Only the three required keys must be filled; an optional field left null is removed before the suggestion is returned, so the result still reads as "only what differs from the defaults".

Docs Server

doc_processing_toolkit.mcp_servers.docs_server

Docs MCP Server.

A local stdio MCP server that gives AI agents structured access to the doc-processing-toolkit documentation bundle. Agents can browse topics, search for relevant chunks, retrieve full content, and access pre-built prompts for common workflows.

Tools provided:

- docs_get_overview: Package metadata and top-level topic summary
- docs_list_topics: Browse chunk catalogue, optionally filtered by tag
- docs_search: Lexical search across titles, tags, keywords, and content
- docs_get_chunk: Retrieve full markdown content of a single chunk
- docs_get_llms_full: Return the complete llms-full.txt for large-context agents
- docs_get_recipe: Retrieve a recipe page by name (fuzzy match supported)

Prompts provided:

- create_agent_quickstart: Step-by-step agent creation for a given provider/model
- troubleshoot_common_errors: Triage steps for common errors with chunk references
- update_docs_bundle: Instructions for regenerating and validating the docs bundle
Example 
python -m doc_processing_toolkit.mcp_servers.docs_server

create_agent_quickstart(provider='anthropic', model='claude-sonnet-4-5')

Step-by-step instructions for creating an agent with a specific provider and model.

Parameters:

Name Type Description Default
provider str

Provider name (anthropic, openai, google, fireworks).

 'anthropic'
model str

Model identifier.

 'claude-sonnet-4-5'

Returns:

Name Type Description
str str

Formatted quickstart instructions as a string.

docs_get_chunk(chunk_id)

Retrieve the full markdown content of a documentation chunk.

Parameters:

Name Type Description Default
chunk_id str

The chunk ID (e.g., 'docs/concepts/agent.md#run-loop-behavior' or 'docs/api/doc_processing_toolkit/agent/core.md#agent-core'). Use docs_search() or docs_list_topics() to discover chunk IDs.

 required

Returns:

Name Type Description
dict Dict[str, Any]

Result containing:

  • chunk_id
  • title
  • path
  • anchor
  • kind
  • content
  • version

Returns {"error": ...} if chunk not found.

docs_get_llms_full()

Return the complete documentation in a single response.

Returns the full llms-full.txt content for agents with large context windows that want to ingest all documentation at once. This is a large response (~335KB). For targeted lookups, prefer docs_search() + docs_get_chunk().

Returns:

Name Type Description
dict Dict[str, Any]

Result containing:

  • content
  • version
  • generated_at
  • size_chars

docs_get_overview()

Get package metadata and a high-level summary of available documentation topics.

Returns package name, version, generation timestamp, chunk count, and a grouped summary of top-level topics by kind (concept, recipe, api). Call this first to orient yourself on what documentation is available.

Returns:

Name Type Description
dict Dict[str, Any]

Result containing:

  • package
  • version
  • generated_at
  • chunk_count
  • topics_by_kind

docs_get_recipe(name_or_id)

Retrieve a recipe page by name or chunk ID.

Supports fuzzy matching: 'session' matches 'session_memory', 'structured' matches 'structured_output_schema', etc.

Parameters:

Name Type Description Default
name_or_id str

Recipe name (e.g., 'session_memory', 'structured_output', 'custom_tools') or a full chunk ID.

 required

Returns:

Name Type Description
dict Dict[str, Any]

Result containing:

  • chunk_id
  • title
  • content
  • kind

For fuzzy matches, also includes all_chunk_ids.

Returns {"error": ...} if recipe not found.

docs_list_topics(tag=None)

List available documentation chunks, optionally filtered by tag.

Parameters:

Name Type Description Default
tag Optional[str]

Filter by tag (e.g., 'concept', 'recipe', 'api', 'agent', 'providers', 'mcp', 'anthropic', 'openai', 'google', 'fireworks', 'tools', 'sessions', 'cost-tracking', 'configuration'). If None, returns all chunks.

 None

Returns:

Name Type Description
list List[Dict[str, Any]]

List of chunk summaries with each summary having the following keys:

  • chunk_id
  • title
  • kind
  • tags

Search documentation by keyword query.

Searches across chunk titles, tags, keywords, and chunk IDs. Returns ranked results with snippets. Use docs_get_chunk() to retrieve the full content of any result.

Parameters:

Name Type Description Default
query str

Search query (e.g., 'Agent class', 'session memory', 'structured output', 'cost tracking').

 required
limit int

Maximum results to return (default 5, max 20).

 5
tag Optional[str]

Optional tag filter to narrow results.

 None

Returns:

Name Type Description
list List[Dict[str, Any]]

List of chunk summaries with each summary having the following keys:

  • chunk_id
  • title
  • kind
  • score (relevance score)
  • snippet (short excerpt from content with query match)
  • tags

troubleshoot_common_errors(error_text='')

Triage steps for common errors with references to relevant documentation chunks.

Parameters:

Name Type Description Default
error_text str

The error message or traceback to troubleshoot.

 ''

Returns:

Name Type Description
str str

Formatted troubleshooting guide as a string.

update_docs_bundle()

Instructions for regenerating the docs bundle and validating it.

Returns:

Name Type Description
str str

Formatted bundle update instructions as a string.

Multimedia Server

doc_processing_toolkit.mcp_servers.multimedia_server

Multimedia MCP Server.

Exposes the toolkit's native multimedia capabilities as MCP tools, so any agent that can call MCP tools can synthesize speech, transcribe audio, and generate or edit images without importing the toolkit.

Tools provided:

  • synthesize_speech: Text-to-speech (OpenAI and Google TTS models)
  • transcribe_audio: Speech-to-text (OpenAI per-minute models, Gemini file transcription, or Gemini audio understanding)
  • generate_image: Text-to-image generation
  • edit_image: Instruction-driven image editing (with pixel masks on OpenAI)
  • image_size_for: Solve for a size a given image model accepts (no API call)

Each tool is a thin wrapper over :mod:doc_processing_toolkit.multimedia: the option validation, provider routing, and cost accounting all happen there, and this module only adapts the call to MCP's JSON-in/JSON-out shape. Every result carries cost and cost_estimated, and a result that made a provider call also carries the _dpt_spend marker, so an Agent calling the tool adds that spend to its own cost (DPT_AGENT_TOOL_REPORTED_COST).

Binary payloads

Audio and images are written to files and the result carries their paths (output_path / paths); it never carries the bytes (0.5.1). Base64 in a tool result is of no use to a model, which can neither hear nor see it, and it floods the context. The folder is the call's output_dir, else DPT_MULTIMEDIA_OUTPUT_DIR, else <system temp>/doc_processing_toolkit/multimedia, per-user and private on Linux and macOS (see :func:multimedia_output_dir). Files are never overwritten: a clashing name gains a _2 suffix. transcribe_audio keeps the transcript in its result and also saves it there as JSON (transcript_path). The include_base64 argument is still accepted and is ignored.

Realtime voice is deliberately not exposed here. MCP tool calls are request/response: a realtime session is a long-lived bidirectional stream whose value is in sub-second audio frames flowing both ways, interruption handling, and a connection held open across many turns. None of that survives being squeezed through one-shot tool calls, so realtime stays a Python API — :func:doc_processing_toolkit.realtime.open_realtime_session.

See Also

multimedia_output_dir(output_dir='')

The folder a multimedia tool writes its file to, created and checked.

The order is the call's output_dir, then DPT_MULTIMEDIA_OUTPUT_DIR (each stripped, blank meaning unset, ~ expanded), then <system temp>/doc_processing_toolkit/multimedia (doc_processing_toolkit-<uid>, private to the user, on Linux and macOS). The system temp folder follows TMPDIR / TEMP / TMP, so inside a sandbox it is the sandbox's own. The folder is created when missing and proved writable by creating and removing a probe file, so a folder the process cannot use fails here, before the provider call. The toolkit never deletes the tools' files.

Parameters:

Name Type Description Default
output_dir str

The output_dir the tool was called with ("" for none).

 ''

Returns:

Name Type Description
str str

The folder, which exists and can be written to.

Raises:

Type Description
MultimediaValidationError

If the folder cannot be created or written to, naming the folder and the variable, so the tool returns an error result before any provider call is billed.
Example 
multimedia_output_dir("")        # e.g. C:\...\Temp\doc_processing_toolkit\multimedia
multimedia_output_dir("out/")    # "out/"