Code2MCP: Automated Repository-to-MCP Transformation

• Code2MCP is a multi-agent, state-graph-based framework that automates converting GitHub repositories into protocol-compliant Model Context Protocol (MCP) services.
• It employs a seven-stage workflow—including analysis, generation, and closed-loop repair—to produce adapter code, tests, documentation, and machine-readable summaries with minimal edits.
• Empirical evaluations demonstrate significant speedups over manual integration with robust, auditable repair mechanisms that enhance tool interoperability.

Code2MCP is a multi-agent, state-graph-based framework for automatically transforming an existing GitHub repository into a Model Context Protocol (MCP) service. It is presented as a response to the “last-mile” integration bottleneck in the MCP ecosystem: although MCP offers a standardized client-server interface for exposing tools, resources, and prompts, most existing software on GitHub is not already packaged as an MCP server. Code2MCP takes a repository URL as its sole input and aims to produce a ready-to-run, protocol-compliant MCP service, together with tests, documentation, and machine-readable summaries, with minimal human intervention (Ouyang et al., 7 Sep 2025).

1. Problem setting and formalization

Code2MCP is framed against the “$N \times M$ problem” in LLM tool integration: if there are $N$ different models or agent applications and $M$ external tools or libraries, then without a standard interface each model or application often requires a custom integration for each tool. The result is duplicated engineering effort, fragmented tool ecosystems, high maintenance cost, and slow interoperability. In this framing, MCP functions as the standard interface intended to decouple tool implementation from agent logic (Ouyang et al., 7 Sep 2025).

Within that setting, Code2MCP formalizes repository-to-service conversion as the key adoption barrier. The paper defines the task as follows: given a repository $\mathcal{R}$, the goal is to synthesize an MCP service $\mathcal{S}$ comprising a set of tools $\{t_i\}$ with natural-language descriptions and input/output schemas, example-first documentation, a smoke-test harness, and machine-readable summaries, such that $\mathcal{S}$ is protocol-compliant and instantiable, exposes stable, high-value functionality suitable for agent composition, and keeps the edit set $E$ empty unless contract reconciliation requires a localized adjustment at adapter boundaries, in which case the edit must be evidence-backed and auditable (Ouyang et al., 7 Sep 2025).

This definition is important because it distinguishes Code2MCP from simple wrapper generation. The framework is not limited to emitting tool signatures. It also synthesizes adapter code, tests, documentation, provenance artifacts, and execution outputs, while attempting to preserve the original repository. The emphasis on a “minimal necessary edits” constraint makes repository preservation and auditability part of the technical objective rather than an incidental implementation detail (Ouyang et al., 7 Sep 2025).

2. State-graph architecture and seven-stage workflow

Code2MCP is implemented as a directed state graph using LangGraph. In this design, nodes correspond to agents or processing stages, edges encode control-flow transitions, and a shared state object accumulates metadata, generated artifacts, execution traces, planning outputs, diffs, and validation results. The paper argues that this state-graph architecture is preferable to purely conversational agent architectures for software engineering because it is more deterministic, modular, traceable, and controllable (Ouyang et al., 7 Sep 2025).

The conversion pipeline has seven stages.

Download clones the target repository from the input URL, prepares a local workspace, and handles public repositories, private repositories with credentials, and specific branches or commits.

Analysis is performed by a Code Analysis Expert agent. It inspects the repository file tree and project metadata, then produces analysis.json, which serves as a strategic blueprint identifying candidate functions, candidate modules, and targets for MCP exposure. In the paper’s algorithmic summary, this stage yields a plan $\pi$ and candidates.

Environment locates dependency files such as requirements.txt and pyproject.toml, constructs an isolated environment using Conda or Venv, and performs a smoke test by attempting to import the project’s main package.

Generate uses a Code Generation Expert agent to synthesize the MCP-facing artifacts, including mcp_service.py, adapter.py, and test_mcp_basic.py, together with documentation.

Run executes the generated smoke test in the isolated environment. If validation succeeds, the pipeline proceeds; if not, it captures full stdout and stderr traces, denoted $\tau$, and transfers control to the debugging stage.

Review is handled by a Senior Software Engineer / Code Fixer agent, which analyzes the failure trace and proposes a minimal correction $N$0, ideally localized at the adapter boundary.

Finalize consolidates successful outputs into final deliverables such as README_MCP.md, workflow_summary.json, and diff_report.md, and the framework may commit generated files to a new Git branch, typically main_mcp, and automatically open a pull request against the original repository (Ouyang et al., 7 Sep 2025).

This workflow makes Code2MCP a repository transformation pipeline rather than a single-shot code generator. The architecture also clarifies the role of MCP in the system: MCP is both the target interface and the organizing constraint for analysis, code generation, validation, and packaging.

3. Closed-loop repair and auditable artifact production

A defining mechanism in Code2MCP is its closed-loop “Run--Review--Fix” cycle. The paper presents this loop in Algorithm 1 using the variables $N$1 for the repository URL, $N$2 for the analysis plan, $N$3 for the retry counter, $N$4 for the retry budget, $N$5 for execution traces, and $N$6 for the proposed edit. The workflow repeatedly runs tests, analyzes failures, applies a minimal fix, updates diffs and provenance, regenerates the service files, and reruns validation until success or retry exhaustion (Ouyang et al., 7 Sep 2025).

The paper uses nbiish/calc as a concrete example. In the initial generation, adapter.py contained the relative import from . import utils, which caused an ImportError in the generated test context. The Review stage diagnosed this as an import-path problem and changed it to from calc import utils. After regeneration and rerun, the tests passed. The paper reports that this self-healing cycle completed in under 90 seconds and contributed to a total successful conversion time of 15 minutes for that repository (Ouyang et al., 7 Sep 2025).

The significance of this loop is twofold. First, it shifts Code2MCP from pure synthesis to autonomous integration debugging. Second, it operationalizes the minimal-edit principle: when repair is necessary, the intended target is the adapter boundary rather than upstream repository logic. The system also records provenance through artifacts such as diff_report.md, which preserves an auditable history of modifications (Ouyang et al., 7 Sep 2025).

A common misconception is that Code2MCP is simply a one-pass repository wrapper generator. The workflow described in the paper contradicts that interpretation. The framework is explicitly iterative, and its core reliability mechanism is post-generation execution followed by bounded repair.

4. Evaluation, metrics, and representative case studies

The empirical study covers six open-source GitHub repositories: googleresearch/esm, nbiish/calc, TextBlob/TextBlob, dateutil/dateutil, ankane/searchkick, and OlafenwaMoses/ImageAI. The paper evaluates three dimensions: efficiency in reducing development time, computational cost of automation, and robustness in handling real-world code. The principal baseline is an estimated manual process by an experienced developer, including repository understanding, wrapper implementation, MCP protocol integration, tests, and documentation (Ouyang et al., 7 Sep 2025).

Repository	Code2MCP Time	Speedup
googleresearch/esm	10 min	~15x
nbiish/calc	15 min	~12x
TextBlob/TextBlob	6 min	~25x
dateutil/dateutil	7 min	~17x
ankane/searchkick	8 min	~17x
OlafenwaMoses/ImageAI	7 min	~21x

Across the benchmark, the paper reports an average manual time of approximately 2.4 hours, an average Code2MCP conversion time of 8.3 minutes, an average speedup of approximately 17.8x, and an average LLM cost of 31.8k tokens per repository (Ouyang et al., 7 Sep 2025).

Two case studies illustrate different facets of the framework. The esm case represents a complex scientific library for protein folding and structure prediction. The paper contrasts a manually cumbersome workflow involving model loading, tokenizer handling, device placement, inference, output conversion, and file writing with a generated MCP-level invocation of mcp_tools.esm.predict_structure(...), which returns a pdb_file_path and message. The system reportedly converted this repository in 10 minutes at approximately 15x speedup, and the final generated service executed successfully in Claude-Code (Ouyang et al., 7 Sep 2025).

The calc case highlights autonomous repair. The final MCP service exposed mathematical tools such as riemann_sum and fourier_transform, and the example is used primarily to demonstrate failure diagnosis and recovery rather than raw synthesis speed (Ouyang et al., 7 Sep 2025).

The evaluation is promising but bounded. The paper does not provide a direct human-user study, another automated baseline, an ablation of the repair loop, repeated-run variance, or evaluation on non-Python repositories. It therefore supports the view of Code2MCP as an effective early framework rather than a fully validated universal repository-to-MCP compiler (Ouyang et al., 7 Sep 2025).

5. Relation to adjacent MCP research

Code2MCP occupies one part of a broader research landscape on making software and applications available through MCP. In that landscape, adjacent work differs mainly in scope and target substrate.

MCPWorld is a unified benchmarking testbed for API, GUI, and API-GUI hybrid computer-use agents. Its central idea is the use of “white-box apps,” namely source-code-available desktop applications that can be revised or recompiled as needed, including by “adding MCP support.” The paper does not present a general repository-to-MCP compiler, but it does describe a practical pipeline for selecting applications, identifying semantically meaningful functions, integrating an MCP server or existing MCP server, adding internal verification hooks, and packaging the result in containers. This places MCPWorld close to Code2MCP conceptually, but its focus is benchmarking open-source desktop applications rather than arbitrary GitHub repository conversion (Yan et al., 9 Jun 2025).

OSWorld-MCP addresses a narrower transformation problem. It presents an automated pipeline that generates code solutions for desktop tasks, filters them through execution, and wraps verified solutions into MCP tools. The final benchmark contains 158 tools, including 72 tools automatically packaged from verified code solutions. This suggests a related but different pipeline: task-solving code to MCP tool wrapping rather than repository-to-service synthesis (Jia et al., 28 Oct 2025).

MCPCorpus contributes a large-scale empirical substrate rather than a generator. It introduces a dataset containing around 13,875 servers and 300 clients, annotated with 20+ normalized attributes including tools, sse_url, server_command, and server_config. A plausible implication is that such a corpus could support Code2MCP-style systems as a template bank, retrieval corpus, or validation reference for real-world MCP configuration patterns (Lin et al., 30 Jun 2025).

These works together indicate that Code2MCP belongs to a broader movement from manual MCP enablement toward automation, validation, and standardization. Its specific contribution is to make repository-to-service conversion itself the central automation target.

6. Security posture, limitations, and open questions

The Code2MCP paper explicitly notes that it does not discuss security in depth, even though the framework automatically clones arbitrary repositories, installs dependencies, executes generated code, and runs tests. It also does not specify hardened sandboxing, network isolation, or a detailed permission model. The paper identifies operational risks such as malicious dependency scripts, dangerous repository code, data exfiltration, and unsafe execution side effects, but leaves them largely unaddressed (Ouyang et al., 7 Sep 2025).

That omission matters because adjacent MCP security research describes a much harsher deployment environment. “MCP Safety Audit” demonstrates that MCP-enabled assistants may be coerced into malicious code execution, remote access control, credential theft, and multi-server Retrieval-Agent DEception chains involving filesystem, Slack, Everything, and Chroma MCP servers (Radosevich et al., 2 Apr 2025). MCPTox shows that tool metadata itself is a prompt surface: on 45 real-world MCP servers and 353 authentic tools, parameter tampering was the most effective tool-poisoning paradigm, with an average attack success rate of 46.7% across agents (Wang et al., 19 Aug 2025). A large-scale risk study of 222 open-source Python MCP server repositories reports that 191 repositories, or 86.0%, contained at least one mapped weakness, with Protocol weaknesses dominating by both finding count and risk-weighted exposure (Kumar et al., 10 Mar 2026).

In that context, a plausible implication is that production-grade Code2MCP pipelines require more than code synthesis and smoke testing. They likely need secure-by-design MCP generation, metadata sanitization, least-privilege wrappers, explicit authorization, safer defaults for filesystem and network access, and repository-level auditing before deployment. Related work on MCP threat analysis and mitigation repeatedly emphasizes that MCP servers are security boundaries rather than passive adapters (Narajala et al., 11 Apr 2025).

The paper’s own limitations are also architectural. It is primarily Python-focused, sensitive to large repositories and non-standard project structures, dependent on environment reproducibility through Conda or Venv rather than stronger deployment isolation, and validated chiefly through smoke tests rather than deep semantic correctness checks. The authors further note the need for future work on larger repositories, more languages, and better accommodation of open-source social etiquette when automatically opening pull requests (Ouyang et al., 7 Sep 2025).

Taken together, these constraints place Code2MCP in a precise historical and technical position. It is an early framework that demonstrates repository-to-MCP conversion can be automated, iteratively debugged, and packaged at useful speed. It is not yet a universal compiler from arbitrary repositories to secure, semantically validated MCP services. The broader MCP literature suggests that the next stage of development will require combining repository transformation with benchmark-driven validation, richer interface semantics, and explicit security controls (Yan et al., 9 Jun 2025).