Metadata-Version: 2.4
Name: vulcai-mcp-forge-cli
Version: 0.2.0
Summary: Generate MCP servers instantly from any OpenAPI, GraphQL, codebase, CLI or website
Project-URL: Homepage, https://mcp-forge.vulcai.io
Project-URL: Repository, https://github.com/huntunman/MCP-FORGE
Project-URL: Changelog, https://github.com/huntunman/MCP-FORGE/blob/main/CHANGELOG.md
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: engine
Requires-Dist: anthropic>=0.30; extra == 'engine'
Requires-Dist: jinja2>=3; extra == 'engine'
Requires-Dist: playwright>=1.44; extra == 'engine'
Provides-Extra: web
Requires-Dist: playwright>=1.44; extra == 'web'
Description-Content-Type: text/markdown

# vulcai-mcp-forge-cli

**Turn any system into a production-ready MCP server — APIs, legacy codebases, CLI tools, internal docs.**

```bash
pip install vulcai-mcp-forge-cli
mcp-forge run https://petstore3.swagger.io/api/v3/openapi.json
```

**Why mcp-forge:**
- **23 languages** including COBOL, Fortran, R, Julia — the only generator that works on real legacy codebases
- **Built-in quality scoring** — every generated server is automatically evaluated on 6 criteria (structure, coverage, auth, docs, fidelity, robustness) with a 0–10 score
- **Security-first** — the CLI runs on your machine; your source code and credentials never leave your infrastructure
- **Agents included** — the public MCP server at `mcp.mcp-forge.vulcai.io` exposes high-level tools so AI agents can generate servers without any pre-parsing

---

## Use directly with AI agents

Connect Claude, Cursor or any MCP client to the mcp-forge public server:

```
https://mcp.mcp-forge.vulcai.io/sse
```

Available tools (no pre-parsing required — just pass a URL):

| Tool | What it does |
|---|---|
| `generate_from_openapi(spec_url)` | Parse an OpenAPI/Swagger spec and generate a server |
| `generate_from_graphql(endpoint_url)` | Introspect a GraphQL endpoint and generate a server |
| `generate_from_website(url)` | Analyze HTML/JS patterns on a page and generate a server |
| `generate_async(source_type, base_url)` | Advanced: submit a job with a pre-built payload |
| `get_job_status(job_id)` | Check status of a running generation |

> For codebase analysis, CLI tool wrapping, or any source not publicly accessible via HTTPS, use the CLI tool — source code and credentials stay on your machine.

---

## What it does

mcp-forge analyses your source, extracts all callable operations, optionally enriches them with an LLM, and writes a fully working MCP server (`server.py` + `requirements.txt`) ready to plug into Claude Desktop, Claude Code, Cursor, VS Code or any MCP-compatible client.

Every generated server includes OAuth 2.0 (Authorization Code + PKCE), rate limiting, multi-tenant token isolation, and SSE transport — out of the box.

Every generated server is automatically evaluated on 6 quality criteria. The `eval_score` (0–10) and detailed report are included in the generation response.

---

## Supported sources

| Source | Auto-detected when | Example |
|---|---|---|
| **OpenAPI / Swagger** | URL or file ending in `.json`, `.yaml`, `.yml` | `mcp-forge run https://api.example.com/openapi.json` |
| **GraphQL** | URL contains `graphql` or ends with `/graphql` | `mcp-forge run https://api.example.com/graphql` |
| **Codebase** | Local directory path | `mcp-forge run ./my-project` |
| **CLI application** | Command name (no slashes, no http) | `mcp-forge run git` |
| **Website** | `http://` or `https://` URL without spec extension | `mcp-forge run https://example.com` |

**Supported languages for codebase analysis:** Python, JavaScript, TypeScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Kotlin, Swift, Scala, Dart, Elixir, R, Fortran, Bash, PowerShell, Groovy, Julia, Lua, COBOL.

---

## Installation

**Requirements:** Python 3.11+ · [Node.js 18+](https://nodejs.org) · [uv](https://docs.astral.sh/uv/)

```bash
pip install vulcai-mcp-forge-cli
```

**Install uv** (used to run generated servers):

```bash
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Website scraping support** (JS-heavy pages / SPAs — requires Playwright):

```bash
pip install "vulcai-mcp-forge-cli[web]"
playwright install chromium
```

---

## License key

Get your license key at [api.mcp-forge.vulcai.io](https://api.mcp-forge.vulcai.io) then register it once in your project directory:

```bash
mcp-forge set-license mfg_live_...
```

This saves the key to a `.env` file and it will be picked up automatically on every `mcp-forge run` call.

---

## Quick start

```bash
# OpenAPI from URL
mcp-forge run https://petstore3.swagger.io/api/v3/openapi.json

# GraphQL
mcp-forge run https://countries.trevorblades.com/graphql

# Local codebase
mcp-forge run ./my-python-project

# CLI tool
mcp-forge run git

# Website
mcp-forge run https://docs.example.com

# Custom output and server name
mcp-forge run https://api.example.com/openapi.json --output ~/mcp-servers --name my_api
```

The generated server is written to `../mcp-forge-output/<server_name>/` by default.

---

## CLI reference

### `mcp-forge run <source>`

| Option | Values | Description |
|---|---|---|
| `--mode, -m` | `auto` · `semi` · `guided` | Generation mode — auto runs silently, semi prompts on ambiguity, guided is fully interactive |
| `--type, -t` | `openapi` · `graphql` · `codebase` · `cli_app` · `website` | Force source type instead of auto-detect |
| `--output, -o` | `<path>` | Output directory (default: `../mcp-forge-output/`) |
| `--name, -n` | `<string>` | Override the generated server name |
| `--name-style, -ns` | `short` · `exhaustive` | Tool naming style |
| `--api-key` | `<string>` | Anthropic API key (overrides `ANTHROPIC_API_KEY`) |
| `--local` | flag | Force local pipeline — no call to the Vulcai API |
| `--no-llm` | flag | Skip LLM enrichment — generate from raw discovery only |
| `--config, -c` | `<file.yaml>` | Load options from a YAML config file (default: `mcp-forge.yaml` if present) |
| `--smoke-test` | flag | Run a smoke test automatically after generation |
| `--functional-test` | flag | Start the server and run a full MCP functional test after generation |

### `mcp-forge set-license <key>`

Save your license key to `.env` in the current directory.

```bash
mcp-forge set-license mfg_live_abc123...
```

### `mcp-forge test <server.py>`

Launch MCP Inspector on a generated server. Opens in your browser. Accepts Windows backslash paths.

```bash
mcp-forge test output/my_server/server.py
```

### `mcp-forge smoke-test <server_dir>`

Validate a generated server **without starting it**. Checks: `server.py` present, Python syntax valid, importable, `mcp` object present, at least 1 `@mcp.tool` registered, VERSION file consistency.

```bash
mcp-forge smoke-test output/my_server
```

### `mcp-forge functional-test <server_dir>`

Start the server and communicate with it via JSON-RPC / stdio — exactly like a real MCP client. Verifies: server starts, MCP handshake succeeds, `tools/list` returns ≥1 tool, count matches VERSION file.

| Option | Description |
|---|---|
| `--timeout, -t` | Max wait time per phase in seconds (default: 15) |

```bash
mcp-forge functional-test output/my_server --timeout 30
```

### `mcp-forge evaluate <server.py>`

Evaluate the quality of a generated server using LLM analysis. Produces a detailed quality report.

| Option | Description |
|---|---|
| `--context, -C <string>` | Additional context — source spec, use case, expected behaviour |
| `--json` | Output raw JSON (useful for CI/CD pipelines) |
| `--save, -s <file.json>` | Save the JSON report to a file |
| `--api-key <string>` | Anthropic API key (overrides `ANTHROPIC_API_KEY`) |

```bash
mcp-forge evaluate output/my_server/server.py --context "Petstore API" --save report.json
```

### `mcp-forge list`

List all generated MCP servers in the output directory. Displays name, generation date, source and tool count.

| Option | Description |
|---|---|
| `--output, -o <path>` | Directory to inspect (default: `../mcp-forge-output/`) |

```bash
mcp-forge list
```

### `mcp-forge info`

Display version info, supported source types and current configuration.

### `mcp-forge --version`

Print the installed version and exit.

---

## Generation modes

| Mode | Description |
|---|---|
| `auto` | Fully automatic — no prompts |
| `semi` | Pauses on ambiguity, interactive where needed |
| `guided` | Step-by-step with full control over every tool |

---

## LLM enrichment

By default, mcp-forge calls the Vulcai API to enrich tool names and descriptions using Claude. Set your license key with `mcp-forge set-license` — no Anthropic key needed in cloud mode.

To run fully locally (requires `[engine]` extras — not publicly distributed):

```bash
mcp-forge run https://api.example.com/openapi.json --local
```

To skip enrichment entirely:

```bash
mcp-forge run https://api.example.com/openapi.json --no-llm
```

---

## Configuration file

Create `mcp-forge.yaml` in your project root:

```yaml
source: https://api.example.com/openapi.json
mode: auto
output: ../mcp-servers
name: my-api-server
name_style: short
no_llm: false
functional_test: true
```

CLI flags always override the config file. Use a custom path with `--config path/to/config.yaml`.

---

## Environment variables

| Variable | Description |
|---|---|
| `FORGE_LICENSE_KEY` | Your mcp-forge license key. Set automatically by `mcp-forge set-license`. |
| `FORGE_API_URL` | Override the Vulcai API endpoint — useful for on-premise deployments. |
| `FORGE_MODE` | Set to `local` to always use the local pipeline. |
| `ANTHROPIC_API_KEY` | Anthropic API key — only needed when running the local pipeline with LLM enrichment. |

---

## Connecting to AI clients

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "my_api": {
      "command": "uv",
      "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
      "cwd": "/path/to/mcp-forge-output/my_api"
    }
  }
}
```

Restart Claude Desktop — your tools appear automatically.

### Claude Code (CLI)

```bash
claude mcp add my_api uv -- run --with mcp mcp run server.py \
  --cwd /path/to/mcp-forge-output/my_api
```

### Cursor

Open **Settings › MCP › Add new global MCP server**:

```json
{
  "my_api": {
    "command": "uv",
    "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
    "cwd": "/path/to/mcp-forge-output/my_api"
  }
}
```

### VS Code (Copilot / Continue)

In `.vscode/mcp.json`:

```json
{
  "servers": {
    "my_api": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
      "cwd": "/path/to/mcp-forge-output/my_api"
    }
  }
}
```

### Windsurf

Open **Settings › Cascade › MCP servers › Add Server**:

```json
{
  "my_api": {
    "command": "uv",
    "args": ["run", "--with", "mcp", "mcp", "run", "server.py"],
    "cwd": "/path/to/mcp-forge-output/my_api"
  }
}
```

### Generic (any MCP-compatible client)

All clients implementing the [MCP spec](https://modelcontextprotocol.io) accept a STDIO transport:

```
command : uv
args    : run --with mcp mcp run server.py
cwd     : /path/to/mcp-forge-output/<server_name>
env     : { "MY_API_KEY": "..." }   ← optional, for authenticated APIs
```

> **Authenticated APIs:** if your API requires credentials, set them in the `env` block. The generated `server.py` reads credentials from environment variables — no secrets are hardcoded.

---

## CI/CD integration

```yaml
- name: Generate MCP server
  run: |
    pip install vulcai-mcp-forge-cli
    mcp-forge run https://api.example.com/openapi.json --mode auto --no-llm
    mcp-forge smoke-test ../mcp-forge-output/my_api
```

---

## Security & Compliance

For data retention, LLM access policies, GDPR compliance, and subprocessors, see the [Trust & Security page](https://api.mcp-forge.vulcai.io/trust).

---

## License

MIT — see [LICENSE](LICENSE).
