Metadata-Version: 2.4
Name: agentport-cli
Version: 0.1.0
Summary: Lightweight, security-first converter between coding-agent config formats (CLAUDE.md, AGENTS.md, Cursor rules, MCP configs, SKILL.md).
License: MIT License
        
        Copyright (c) 2026 AgentPort contributors
        
        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.
        
Project-URL: Homepage, https://github.com/omrgpt/agentport
Project-URL: Repository, https://github.com/omrgpt/agentport
Project-URL: Issues, https://github.com/omrgpt/agentport/issues
Project-URL: Changelog, https://github.com/omrgpt/agentport/blob/main/CHANGELOG.md
Keywords: agents,claude,codex,cursor,opencode,mcp,skills,converter
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
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.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# AgentPort

**One config, every coding agent.** A lightweight, security-first converter
between the config formats of AI coding assistants.

You write your guidelines once. AgentPort ports them everywhere.

```
                ┌──────────────┐
   AGENTS.md ──▶│              ├──▶ CLAUDE.md            (Claude Code)
   SKILL.md  ──▶│  agentport   ├──▶ .cursor/rules/*.mdc  (Cursor)
   mcp.json  ──▶│              ├──▶ GEMINI.md / .rules / .clinerules / ...
                └──────────────┼──▶ .github/copilot-instructions.md
                               ├──▶ opencode.json / codex config.toml
                               └──▶ .claude/skills / .opencode/skill / ...
```

## Why

Every coding assistant invented its own instruction format: `AGENTS.md`,
`CLAUDE.md`, `.cursorrules`, `copilot-instructions.md`, `.windsurfrules`,
`.clinerules`, `GEMINI.md`, ... — plus per-tool MCP server configs and skill
formats. Keeping them in sync by hand is tedious and error-prone. Existing
tools solve only one slice (usually rules propagation) and tend to pull in a
dependency tree.

AgentPort is the missing **converter**: any format → any other format, for
instructions *and* MCP configs *and* skills.

- **Zero dependencies.** Pure Python stdlib (3.10+). One `pip install`, no
  supply-chain surface.
- **Security-first.** No network. No eval. Path containment, size caps,
  symlink refusal, duplicate-key rejection, atomic writes, secret masking.
  See [SECURITY.md](SECURITY.md).
- **Lossless where possible, honest where not.** When a target format lacks a
  feature (e.g. Codex has no "disabled" flag for servers), AgentPort warns
  instead of silently dropping data.
- **Deterministic output.** Same input + same flags = byte-identical files.

## Install

```
pip install .
```

or run straight from a checkout:

```
python -m agentport --help        # from repo root (uses src/)
python selftest.py                # dependency-free verification
```

## Quick start

```
# What does my project already have?
agentport detect

# Write AGENTS.md once, propagate to all other tools
agentport instructions sync --from agents          # skips existing files
agentport instructions sync --force                # overwrite all targets

# Single conversion, with preview
agentport instructions convert AGENTS.md --to cursor --dry-run --diff
agentport instructions convert AGENTS.md --to copilot --force

# Port your Claude Desktop MCP servers into VS Code + OpenCode + Codex
agentport mcp convert claude_desktop_config.json --to vscode
agentport mcp convert claude_desktop_config.json --to opencode --out opencode.json
agentport mcp convert claude_desktop_config.json --to codex   --out ~/.codex/config.toml

# Inspect an MCP config without leaking secrets
agentport mcp show .cursor/mcp.json

# Skills: validate against the spec, then install everywhere
agentport skills validate ./my-skill
agentport skills import ./my-skill --to claude     # -> .claude/skills/my-skill
agentport skills import ./my-skill --to opencode   # -> .opencode/skill/my-skill
agentport skills export  ./my-skill --to cursor    # -> .cursor/rules/my-skill.mdc
```

## Supported formats

### Instructions (`instructions convert|sync`)

| Key             | File                              | Tool                 |
|-----------------|-----------------------------------|----------------------|
| `agents`        | `AGENTS.md`                       | Codex, OpenCode, many |
| `claude`        | `CLAUDE.md`                       | Claude Code          |
| `gemini`        | `GEMINI.md`                       | Gemini CLI           |
| `amp`           | `AGENT.md`                        | Amp                  |
| `zed`           | `.rules`                          | Zed                  |
| `windsurf`      | `.windsurfrules`                  | Windsurf             |
| `cline`         | `.clinerules`                     | Cline                |
| `aider`         | `CONVENTIONS.md`                  | Aider                |
| `copilot`       | `.github/copilot-instructions.md` | GitHub Copilot       |
| `cursor`        | `.cursor/rules/*.mdc`             | Cursor (frontmatter) |
| `cursor-legacy` | `.cursorrules`                    | Cursor (legacy)      |

Cursor `.mdc` files get synthesized frontmatter (`description`, `globs`,
`alwaysApply`); converting *from* `.mdc` strips it back off. Override with
`--description/--globs/--always-apply`.

### MCP server configs (`mcp convert|show`)

| Family    | Typical file                          | stdio | http/sse | disabled flag |
|-----------|---------------------------------------|-------|----------|---------------|
| `claude`  | `claude_desktop_config.json`          | yes   | warn     | no            |
| `cursor`  | `.cursor/mcp.json`                    | yes   | yes      | via extra key |
| `vscode`  | `.vscode/mcp.json`                    | yes   | yes      | no            |
| `opencode`| `opencode.json(c)` (`"mcp"` section)  | yes   | yes      | `enabled`     |
| `codex`   | `~/.codex/config.toml`                | yes   | recent   | no            |
| `windsurf`| `~/.codeium/windsurf/mcp_config.json` | yes   | warn     | no            |
| `gemini`  | `~/.gemini/settings.json`             | yes   | warn     | no            |

Semantics:

- Default is a **merge**: existing servers are kept; name collisions keep the
  existing entry unless `--conflict overwrite`; `--replace` discards the old
  file content; `--prune` drops servers absent from the source.
- Project-scoped targets (cursor/vscode/opencode) merge in place at their
  canonical path. Machine-global targets (claude/codex/windsurf/gemini)
  require explicit `--out` so AgentPort never touches your home directory on
  its own.
- Unknown keys are preserved per-server so round-trips don't shred exotic
  options. Existing top-level keys (`$schema`, `theme`, `inputs`, ...) are
  preserved too.
- OpenCode's `"command": [cmd, arg...]` array form and `environment` map are
  translated automatically; `enabled: false` maps to the disabled flag.

### Skills (`skills validate|normalize|import|export`)

Validates the common SKILL.md spec (lowercase-hyphen `name` ≤ 64 chars,
`description` ≤ 1024 chars, body required). `normalize` auto-fixes casing,
whitespace and over-long descriptions. Import copies auxiliary files under
strict caps (200 files / 2 MiB) while skipping symlinks and executables.
Claude-only `allowed-tools` is moved under `metadata` for non-Claude targets.

## Safety & exit codes

| Code | Meaning                                                        |
|------|----------------------------------------------------------------|
| 0    | success                                                        |
| 1    | usage/format errors (bad target, invalid frontmatter, ...)     |
| 2    | safety refusal (path escape, oversized/binary input, symlink)  |
| 3    | conflict (existing file; re-run with `--force`)                |
| 70   | unexpected bug (please report)                                 |

Add `--strict` to turn warnings into failures, `--dry-run`/`--diff` to
preview, `--root <dir>` to operate on another project.

## Use it from your agent

A ready-made skill is included so Claude Code / OpenCode / agents-spec
clients can drive AgentPort themselves:

```
agentport skills import integration/skills/agent-port --to claude
```

## Comparison

| | AgentPort | Ruler | ad-hoc scripts |
|---|---|---|---|
| Instructions propagation | yes | yes | partial |
| Bidirectional conversion | yes | no | no |
| MCP config conversion | yes (7 clients) | no | rare |
| Skills handling | yes | no | no |
| Dependencies | **0** | Node.js tree | varies |

## Development

```
pip install -e .[dev]
python selftest.py && pytest tests -q
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for design rules and how to add a new
target format (it's a registry entry plus round-trip tests).

## License

MIT — see [LICENSE](LICENSE).
