Extending with Custom Tools
Relevant source files
The following files were used as context for generating this wiki page:
Extending the tldw_server with custom tools is primarily achieved through the Model Context Protocol (MCP) Unified module and the core service layer. This architecture allows the platform to act as a personal knowledge assistant by integrating various media processing, search, and knowledge management capabilities into an agentic framework. By following the "thin endpoints, fat core modules" pattern, developers can implement complex domain logic as tools that are accessible via REST, WebSockets, or MCP-aware clients.
Sources: Docs/Architecture.md, AGENTS.md, CLAUDE.md
Tooling Architecture and MCP Integration
The project utilizes a production-grade MCP Unified module to expose backend functionality as tools for AI agents. This system is centralized under tldw_Server_API/app/core/MCP_unified/. Tools are mapped from domain-specific modules (such as media, knowledge, or notes) and provided to agentic clients with integrated Role-Based Access Control (RBAC) and JWT authentication.
Component Relationship
The diagram below illustrates how a custom tool implemented in a core module is exposed through the MCP layer to external clients.
The system is designed to keep logic within the core domain services, typically found in tldw_Server_API/app/core/. This ensures that tools are reusable across different interface types, including the Next.js WebUI and external MCP-aware IDE integrations.
Sources: Docs/Architecture.md, AGENTS.md, CLAUDE.md
Implementing Tool Logic in Core Modules
When extending the system, new functionality should be added as a sub-package within tldw_Server_API/app/core/. This approach follows the project's philosophy of maintaining specialized modules for distinct capabilities.
Key Extension Points
| Extension Category | Directory Path | Description |
|---|---|---|
| Media Processing | app/core/Ingestion_Media_Processing/ | Tools for downloading, transcoding, or extracting metadata from media. |
| Search & RAG | app/core/RAG/ | Custom retrieval pipelines combining vector search and FTS5. |
| Writing Tools | app/core/Writing/ | Capabilities for drafting, rewriting, and formatting text. |
| Knowledge Management | app/core/Notes/ | Tools for interacting with the notebook-style note-taking system. |
| Orchestration | app/services/ | Background services for long-running jobs or scheduled tasks. |
Sources: Docs/Architecture.md, AGENTS.md, tldw_Server_API/app/core/Writing/README.md
Example: Writing Assistance Tools
The Writing module provides a specific blueprint for extending the system with generative features. It focuses on several key capabilities that can be exposed as tools:
- Drafting & Outlining: Generating initial content structures.
- Rewriting & Formatting: Modifying existing text based on user prompts.
- Contextual Inputs: Processing prompts alongside provided metadata or search results.
Sources: tldw_Server_API/app/core/Writing/README.md
Orchestration: Jobs vs. Scheduler
For tools that perform asynchronous work, developers must choose between the Jobs system and the Scheduler system. This choice determines how the tool's execution is tracked and managed.
Jobs System*: Use this for user-facing work that requires administrative controls like pause/resume, retries, or quotas. It uses the WorkerSDK for background processing.
- Scheduler System: Use this for internal system orchestration, such as task dependencies or handling watchlists. Tasks are registered via the
@taskdecorator.
Sources: AGENTS.md:144-158
Workflow-Based Tooling (Kanban Primitives)
Advanced tool extensions can implement "safe orchestrator" primitives, as seen in the Kanban module. These tools allow autonomous agents to interact with complex state machines safely by using:
- CAS (Compare-And-Swap): Ensuring updates only happen if the version matches.
- Leases: Preventing multiple agents from acting on the same resource simultaneously.
- Idempotency Keys: Ensuring a tool execution can be safely retried without duplicate side effects.
Workflow Transition Flow
This sequence diagram shows the safe execution of a state transition tool.
Technical Standards for Extensions
To maintain consistency and security, all custom tools must adhere to the following standards:
- Pydantic Models: All tool inputs and outputs must use Pydantic schemas defined in
app/api/v1/schemas/. - Dependency Injection: Use FastAPI-style dependencies for DB connections and service instances.
- Database Abstraction: No raw SQL should be used. All operations must go through the abstractions in
app/core/DB_Management/. - Logging: Use
logurufor all telemetry and debugging information. - Security Validation: Run
Banditon the new code scope to ensure no security vulnerabilities are introduced.
Sources: Docs/Architecture.md, AGENTS.md, CLAUDE.md
Extending tldw_server involves implementing logic within the core domain modules and exposing that logic through the MCP Unified layer. By leveraging the platform's existing Job and Scheduler systems, developers can create robust, safe, and agent-accessible tools that integrate seamlessly with the RAG and media analysis pipelines.