MCP Tool Definitions
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Model Context Protocol (MCP) Tool Definitions represent the standardized interface layer between DeepCode agents and the underlying system environment. These definitions enable Large Language Models (LLMs) to interact with the file system, execute code, and perform complex searches through a structured JSON schema interface. By isolating tool definitions from core logic, the system provides a clean, modular architecture for iterative code development and paper reproduction.
The MCP architecture in DeepCode utilizes specialized servers—primarily the code-implementation-server and the code-reference-indexer—which expose capabilities that agents call using the schemas defined in the configuration files. This setup ensures that agents operate within a controlled workspace with strict path validation and operation logging.
Sources: config/mcp_tool_definitions.py:1-18, workflows/code_implementation_workflow_index.py:10-15, tools/code_implementation_server.py:10-30
Architecture and Configuration
The MCP system follows a client-server model where tool definitions are centralized to provide a consistent API for different agent workflows. The configuration is primarily managed through the MCPToolDefinitions class, which aggregates individual tool schemas into functional sets.
System Overview
The following diagram illustrates the relationship between the tool definitions, the MCP server, and the agent workflows.
The workflow manages the agent, which uses the JSON schemas to format tool calls that are executed by the MCP servers against the local workspace.
Sources: config/mcp_tool_definitions.py:20-35, workflows/code_implementation_workflow_index.py:205-230, tools/code_implementation_server.py:45-60
Tool Categories
The tools are organized into functional sets, primarily the code_implementation set, which is critical for transforming research papers into working code.
File Operations
These tools provide the primary interface for reading and writing data within the agent's designated workspace.
| Tool Name | Description | Required Parameters |
|---|---|---|
read_file | Reads file content with optional line ranges. | file_path |
write_file | Writes content to a file, creating directories if needed. | file_path, content |
read_code_mem | Checks for specific file summaries in the project's memory file. | file_paths |
set_workspace | Configures the root directory for all subsequent file operations. | workspace_path |
The read_code_mem tool is specifically designed to read from implement_code_summary.md, allowing agents to understand previously implemented modules without re-reading entire source files.
Sources: config/mcp_tool_definitions.py:44-106, tools/code_implementation_server.py:228-260
Execution and Search
These tools allow agents to validate their implementations and find relevant code patterns.
| Tool Name | Description | Key Features |
|---|---|---|
execute_python | Executes Python code in a temporary file and returns output. | Timeout support, capture stdout/stderr. |
execute_bash | Runs shell commands within the workspace. | Security filtering for dangerous commands. |
search_code | Searches for patterns across multiple files. | Regex support, file pattern filtering. |
search_code_references | Unified tool for searching reference code in JSON indexes. | Relevance scoring, dependency identification. |
The execute_bash tool includes a safety layer that blocks dangerous operations such as rm -rf, sudo, or chmod 777.
Sources: config/mcp_tool_definitions.py:108-164, tools/code_implementation_server.py:173-225, tools/code_reference_indexer.py:250-280
Implementation Logic
Server-Side Path Validation
The code_implementation_server.py implements a strict validate_path function to ensure that all tool operations stay within the initialized WORKSPACE_DIR.
def validate_path(path: str) -> Path:
"""Validate if path is within workspace"""
if WORKSPACE_DIR is None:
initialize_workspace()
full_path = (WORKSPACE_DIR / path).resolve()
if not str(full_path).startswith(str(WORKSPACE_DIR)):
raise ValueError(f"Path {path} is outside workspace scope")
return full_path
Sources: tools/code_implementation_server.py:86-94
Iterative Development Flow
The tools are designed to support a specific development cycle: dependency analysis, implementation, and testing.
This sequence demonstrates how the agent leverages both the implementation memory (via read_code_mem) and external references (via search_code_references) before writing and testing code.
Sources: workflows/code_implementation_workflow_index.py:270-310, workflows/agents/memory_agent_concise.py:530-560
Advanced Reference Indexing
The search_code_references tool, defined in config/mcp_tool_definitions_index.py and implemented in tools/code_reference_indexer.py, provides sophisticated code discovery. It calculates relevance scores based on filename similarity, file types, and keyword matching.
Reference Data Structure
The indexer processes JSON index files that contain:
- File Summaries: Path, type, main functions, and key concepts.
- Relationships: Confidence scores and usage suggestions for specific target files.
- Implementation Suggestions: Pattern matching for function names and dependencies.
Sources: tools/code_reference_indexer.py:35-85, tools/code_reference_indexer.py:200-245
Conclusion
MCP Tool Definitions provide the essential scaffolding for the DeepCode agentic system. By standardizing how agents interact with the environment through modular servers and structured schemas, the system achieves high reliability in automated code implementation. The combination of workspace safety, operation logging, and specialized memory-reading tools allows agents to manage complex, multi-file projects effectively.
Sources: tools/code_implementation_server.py:465-485, workflows/code_implementation_workflow_index.py:465-510