Metadata-Version: 2.4
Name: agentweld
Version: 0.2.0
Summary: Turn any MCP server into a curated, composable, A2A-ready agent.
Project-URL: Homepage, https://github.com/sheshnath08/agentweld
Project-URL: Repository, https://github.com/sheshnath08/agentweld
Project-URL: Bug Tracker, https://github.com/sheshnath08/agentweld/issues
Project-URL: Changelog, https://github.com/sheshnath08/agentweld/blob/main/CHANGELOG.md
Author-email: Sheshnath Yadav <sheshnathyadav08@gmail.com>
License: MIT License
        
        Copyright (c) 2026: Sheshnath Yadav
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: a2a,agent,agentic,llm,mcp,model-context-protocol,tool-curation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Code Generators
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: anyio>=4.4
Requires-Dist: httpx>=0.27
Requires-Dist: jinja2>=3.1
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic-settings>=2.3
Requires-Dist: pydantic>=2.7
Requires-Dist: rich>=13.7
Requires-Dist: ruamel-yaml>=0.18
Requires-Dist: typer[all]>=0.12
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.28; extra == 'anthropic'
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: enrich
Requires-Dist: anthropic>=0.28; extra == 'enrich'
Provides-Extra: openai
Requires-Dist: openai>=1.30; extra == 'openai'
Description-Content-Type: text/markdown

# agentweld

> Turn any MCP server into a curated, composable, A2A-ready agent.

[![PyPI version](https://img.shields.io/pypi/v/agentweld)](https://pypi.org/project/agentweld/)
[![Python 3.11+](https://img.shields.io/pypi/pyversions/agentweld)](https://pypi.org/project/agentweld/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![CI](https://github.com/sheshnath08/agentweld/actions/workflows/ci.yml/badge.svg)](https://github.com/sheshnath08/agentweld/actions/workflows/ci.yml)

## What is agentweld?

The MCP ecosystem has servers — lots of them. What it's missing is a way to turn those servers into purposeful, well-described, discoverable agents. Raw MCP servers expose dozens or hundreds of tools with weak descriptions, inconsistent naming, and no quality signal. Clients have no way to know which tools are useful, what they do, or how to combine them.

**agentweld** solves both problems. It connects to one or more MCP servers, runs a quality scan across every exposed tool, lets you curate the results (filter, rename, enrich descriptions), then generates a complete set of deployment artifacts: an A2A-valid agent card, a tool manifest, a system prompt, and a README — all from a single `agentweld.yaml`.

## The Pipeline

```
SOURCE LAYER  (MCP servers → tools/list)
  ↓  ToolDefinition[]
CURATION ENGINE  (quality scanner → rule-based curator → LLM enrichment)
  ↓
COMPOSITION LAYER  (namespace merge, conflict resolution)
  ↓
GENERATORS  →  agent_card.json  /  mcp.json  /  system_prompt.md  /  README.md
```

## Quick Start

### Install

```bash
pip install agentweld
```

### 5-command walkthrough

```bash
# 1. Scaffold a project from an MCP server
#    --trust is required for stdio sources (spawning npx is code execution)
$ agentweld init "npx @modelcontextprotocol/server-github" --trust
WARNING: --trust flag set. Spawning subprocess: npx @modelcontextprotocol/server-github
Connecting to npx @modelcontextprotocol/server-github...
Discovered 26 tools.
Created ./agentweld.yaml

# 2. (Optional) Add a second source
$ agentweld add "npx @linear/mcp" --trust

# 3. Check tool quality before generating
$ agentweld inspect
┌──────────┬───────┬─────────────┐
│ Source   │ Tools │ Avg Quality │
├──────────┼───────┼─────────────┤
│ github   │  26   │   0.54 ⚠    │
│ linear   │  24   │   0.71      │
└──────────┴───────┴─────────────┘

# 4. Edit agentweld.yaml to filter, rename, or override descriptions
#    (see Configuration Reference below)

# 5. Generate artifacts
$ agentweld generate
Generated 4 artifact(s) in ./agent:
  • agent_card.json
  • mcp.json
  • system_prompt.md
  • README.md
```

## CLI Reference

### `agentweld init`

Scaffold a new `agentweld.yaml` from an MCP source.

```
agentweld init SOURCE [OPTIONS]

Arguments:
  SOURCE    MCP server command (stdio) or URL (http/https)

Options:
  --from TEXT         Source type [default: mcp]
  --trust             Trust and execute the stdio command (required for npx/docker)
  -o, --output PATH   Output directory [default: .]
  -n, --name TEXT     Agent name
```

> **Security:** `--trust` is required for any stdio source because spawning `npx`, `docker`, or any arbitrary command is code execution. HTTP/HTTPS sources do not require it.

### `agentweld add`

Add another MCP source to an existing project.

```
agentweld add SOURCE [OPTIONS]

Arguments:
  SOURCE    MCP server command (stdio) or URL (http/https)

Options:
  --from TEXT         Source type [default: mcp]
  --trust             Trust and execute the stdio command
  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
```

### `agentweld inspect`

Inspect tools and quality metrics for all configured sources.

```
agentweld inspect [OPTIONS]

Options:
  --source            Show raw tools per source (pre-curation)
  --final             Show post-curation tools
  --conflicts         Show naming conflicts across sources
  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
```

### `agentweld generate`

Run the full pipeline and write artifacts to the output directory.

```
agentweld generate [OPTIONS]

Options:
  --force             Overwrite existing artifacts and bypass the quality block gate
                      (warn-zone warnings are always shown)
  --only TEXT         Only generate specific artifacts (repeatable):
                      agent_card | tool_manifest | system_prompt | readme
  --enrich            Run an LLM enrichment pass on discovered tools before
                      generating. Writes improved descriptions back to
                      agentweld.yaml, then reloads config. Requires
                      pip install agentweld[anthropic] or agentweld[openai].
  -o, --output-dir PATH   Override the output directory from agentweld.yaml
  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
```

### `agentweld lint`

Scan tool quality across all configured sources and report issues. Exits with code 1 if any tool is below the `quality.block_below` threshold — suitable for use in CI.

```
agentweld lint [OPTIONS]

Options:
  --source TEXT       Filter to a single source ID
  --min-score FLOAT   Only show tools at or below this score [default: 0.0 = all]
  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
```

Example output:

```
 SCORE  SOURCE   NAME                    FLAGS                    DESCRIPTION
  0.85  github   list_pull_requests      none                     List pull requests in a r...
  0.50  github   get                     poor_naming, weak_desc   Gets.
  0.30  github   post                    poor_naming, missing_...  Posts data.

Summary: 3 scanned, 2 below warn (0.6), 1 below block (0.4)
```

### `agentweld preview`

Same as `generate` but writes to a temp directory and prints artifact contents. Nothing is written to your project.

```
agentweld preview [OPTIONS]

Options:
  -c, --config PATH   Path to agentweld.yaml [default: ./agentweld.yaml]
```

## Configuration Reference

`agentweld.yaml` is the single source of truth for the entire pipeline. Here is an annotated example:

```yaml
meta:
  created_at: "2026-01-01T00:00:00+00:00"
  updated_at: "2026-01-01T00:00:00+00:00"

agent:
  name: "My Dev Agent"
  description: "An agent for GitHub and Linear workflows."
  version: "0.1.0"

sources:
  - id: github
    type: mcp_server
    transport: stdio
    command: "npx @modelcontextprotocol/server-github"
    # env:
    #   GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_TOKEN}"

  - id: linear
    type: mcp_server
    transport: streamable-http
    url: "https://mcp.linear.app/sse"

tools:
  filters:
    github:
      # include and exclude are mutually exclusive — use one or the other
      include:
        - search_repositories
        - create_issue
        - list_pull_requests
      # exclude:
      #   - delete_repository

  rename:
    "github::search_repositories": search_repos
    "linear::create_issue": linear_create_issue

  descriptions:
    # Written here by `agentweld enrich` — safe to edit manually too
    search_repos: "Search GitHub repositories by keyword, language, or topic."

quality:
  warn_below: 0.6     # Print a warning table during generate for tools below this score
  block_below: 0.4    # Quality gate: fail generate if any tool score < this threshold
                      # Use --force to bypass

composition:
  conflict_strategy: prefix   # prefix | explicit | error
                              # prefix: prepend source_id:: to conflicting names
                              # explicit: require rename in tools.rename
                              # error: abort on any conflict

a2a:
  skills:
    - id: code-search
      name: "Code Search"
      description: "Search repositories and navigate codebases."
      tags: [github, search]

generate:
  output_dir: ./agent
  emit:
    agent_card: true
    tool_manifest: true
    system_prompt: true
    readme: true
```

## Generated Artifacts

| Artifact | Path | Purpose |
|---|---|---|
| `agent_card.json` | `<output_dir>/agent_card.json` | A2A Agent Card, suitable for hosting at `/.well-known/agent.json` |
| `mcp.json` | `<output_dir>/mcp.json` | Tool manifest for MCP clients |
| `system_prompt.md` | `<output_dir>/system_prompt.md` | LLM system prompt describing the agent and its tools |
| `README.md` | `<output_dir>/README.md` | Quickstart for users of the generated agent |

## Plugin System

agentweld discovers third-party source adapters via the `agentweld.adapters` entry-point group. No inheritance from agentweld internals is required — structural subtyping (Protocol) is used.

**Implement the `SourceAdapter` protocol:**

```python
# my_package/adapter.py
from __future__ import annotations
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from agentweld.models.config import SourceConfig
    from agentweld.models.tool import ToolDefinition


class MyAdapter:
    async def introspect(self, config: SourceConfig) -> list[ToolDefinition]:
        """Connect to the source and return normalized ToolDefinition objects."""
        ...

    async def health_check(self, config: SourceConfig) -> bool:
        """Return True if the source is reachable; False otherwise. Must not raise."""
        ...
```

**Register it in your package's `pyproject.toml`:**

```toml
[project.entry-points."agentweld.adapters"]
my-transport = "my_package.adapter:MyAdapter"
```

After `pip install my-package`, agentweld discovers your adapter automatically. Use the transport key (`my-transport`) as the `--from` argument when running `init` or `add`.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, code quality requirements, and the PR process.

## License

MIT — see [LICENSE](LICENSE).
