Metadata-Version: 2.4
Name: vulcai-mcp-forge-cli
Version: 0.1.0
Summary: Generate MCP servers instantly from any OpenAPI, GraphQL, codebase, CLI or website
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: playwright>=1.44
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'
Description-Content-Type: text/markdown

# mcp-forge

Generate production-ready [MCP](https://modelcontextprotocol.io) servers instantly from any source — OpenAPI spec, GraphQL schema, codebase, CLI tool, or website.

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

## 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 or any MCP client.

## Supported sources

| Source | Example |
|---|---|
| OpenAPI / Swagger | `mcp-forge https://api.example.com/openapi.json` |
| GraphQL | `mcp-forge https://countries.trevorblades.com/graphql` |
| Codebase (20+ languages) | `mcp-forge ./my-project` |
| CLI application | `mcp-forge git` |
| Website | `mcp-forge https://docs.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

```bash
pip install mcp-forge
```

Requires Python 3.11+.

For website scraping support:
```bash
playwright install chromium
```

## Quick start

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

# From a local GraphQL schema
mcp-forge ./schema.graphql --type graphql

# From a codebase
mcp-forge ./my-python-project

# From a CLI tool
mcp-forge ffmpeg --type cli_app

# Specify output directory and server name
mcp-forge 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 (outside the project directory).

## Options

```
mcp-forge [SOURCE] [OPTIONS]

Arguments:
  SOURCE    URL, OpenAPI file, GraphQL schema, CLI command, or directory

Options:
  --mode, -m        auto | semi | guided  (default: auto)
  --output, -o      Output directory      (default: ../mcp-forge-output)
  --type, -t        Force source type: openapi | graphql | codebase | cli_app | website
  --name, -n        Server name           (default: inferred from source)
  --name-style, -ns short | exhaustive    (default: short)
  --no-llm          Skip LLM enrichment
  --smoke-test      Run smoke test after generation
  --functional-test Run functional MCP test after generation
  --config, -c      Path to mcp-forge.yaml config file
  --api-key         Anthropic API key (or set ANTHROPIC_API_KEY)
```

## Modes

| Mode | Description |
|---|---|
| `auto` | Fully automatic — no prompts, JSON output on stdout |
| `semi` | Confirms key decisions, interactive where needed |
| `guided` | Step-by-step with full control over every tool |

## LLM enrichment

By default, mcp-forge uses Claude (Anthropic) to improve tool names and descriptions. Set your API key:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
mcp-forge https://api.example.com/openapi.json
```

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

## Config file

Create `mcp-forge.yaml` in your project root (see `mcp-forge.example.yaml`):

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

Run with:
```bash
mcp-forge --config mcp-forge.yaml
```

## Testing generated servers

```bash
# Smoke test — checks import and mcp object
mcp-forge smoke-test ../mcp-forge-output/my_server

# Functional test — starts server, MCP handshake, calls every tool
mcp-forge functional-test ../mcp-forge-output/my_server
```

## Connecting the generated server to an AI agent

Once mcp-forge has generated your server, you need to register it in your AI client so it can call the tools.

### 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 in the conversation.

### 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
```

Or edit `.mcp.json` at the root of your project:

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

### Cursor

Open **Settings > MCP > Add new global MCP server** and paste:

```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` at the root of your workspace:

```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 **Windsurf 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"
  }
}
```

### Any MCP-compatible client (generic)

All clients that implement the [MCP spec](https://modelcontextprotocol.io) accept a STDIO transport. The pattern is always the same:

```
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
```

> **Tip — authenticated APIs:** if your server was generated from an API that requires authentication, set the relevant environment variable in the `env` block. The generated `server.py` reads credentials from environment variables — no secrets are hardcoded.

---

## CI/CD integration

GitHub Actions, Jenkins and GitLab CI pipeline templates are included in the `ci/` directory and generated alongside each server.

Example GitHub Actions step:
```yaml
- name: Generate MCP server
  run: |
    pip install mcp-forge
    mcp-forge https://api.example.com/openapi.json --mode auto --no-llm
```

## License

MIT — see [LICENSE](LICENSE).
