Metadata-Version: 2.4
Name: coreforged-mcp
Version: 0.1.0
Summary: MCP gateway that docks multiple servers behind one endpoint with named loadout profiles
Author-email: CoreForged LLC <corporate@coreforged.com>
License: MIT
Project-URL: Homepage, https://coreforged.com/products/coreforged-mcp
Project-URL: Repository, https://github.com/coreforged/coreforged-mcp
Project-URL: Documentation, https://github.com/coreforged/coreforged-mcp#readme
Keywords: mcp,claude,ai,gateway,plugins
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Libraries
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2,>=1.0.0
Provides-Extra: keyring
Requires-Dist: coreforged-mcp; extra == "keyring"
Provides-Extra: all
Requires-Dist: coreforged-mcp; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-asyncio>=0.23; extra == "test"
Dynamic: license-file

# CoreforgedMCP

**One MCP server to dock them all.**

CoreforgedMCP is a gateway that consolidates multiple MCP servers behind a single endpoint. Instead of configuring 5 separate servers in your `.mcp.json`, you configure one — and control which plugins load with a single environment variable.

```
Before: 5 servers × 5 processes × 5 config blocks
After:  1 server  × 1 process  × 1 config block
```

## Quick Start

```bash
pip install coreforged-mcp
coreforged-mcp init
```

This adds CoreforgedMCP to your `.mcp.json`. Restart Claude Code — you're running.

## What You Get

### The Gateway (free, open source)

- **Plugin docking** — native Python plugins load in-process; proxy plugins spawn as subprocesses
- **Named loadouts** — switch your entire tool stack by setting `COREFORGED_LOADOUT=analytics`
- **Plugin discovery** — drop a plugin into `~/.coreforged/plugins/` and it auto-loads
- **Cross-platform** — Windows, Mac, Linux

### KeyRing (bundled)

Your API keys never enter the conversation. The keyring retrieves the secret, makes the authenticated API call, and returns only the response data. Every checkout is logged.

```
Agent: "Call the GitHub API with my token"
  → KeyRing retrieves token from encrypted store
  → KeyRing makes the API call
  → KeyRing returns the response data
  → Token never appears in tool results or context
```

## Usage

### Basic (default plugins)

```json
{
  "mcpServers": {
    "coreforged": {
      "command": "coreforged-mcp",
      "args": ["run"]
    }
  }
}
```

### With a loadout

```json
{
  "mcpServers": {
    "coreforged": {
      "command": "coreforged-mcp",
      "args": ["run"],
      "env": {
        "COREFORGED_LOADOUT": "analytics"
      }
    }
  }
}
```

### Specific plugins only

```json
{
  "mcpServers": {
    "coreforged": {
      "command": "coreforged-mcp",
      "args": ["run"],
      "env": {
        "COREFORGED_PLUGINS": "keyring,my-custom-plugin"
      }
    }
  }
}
```

## Installing Plugins

### From a zip file

```bash
coreforged-mcp install-plugin analytics-bundle.zip --key YOUR_LICENSE_KEY
```

Plugins install to `~/.coreforged/plugins/` and are discovered automatically on next restart.

### From a directory

Drop any directory with a `plugin.json` manifest into `~/.coreforged/plugins/`:

```
~/.coreforged/plugins/
├── my-plugin/
│   ├── plugin.json
│   └── server.py
```

## Writing a Plugin

A plugin is any Python module with a FastMCP instance. If it runs standalone, it docks into the gateway.

**1. Write the server**

```python
# my-plugin/server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-plugin", instructions="What this does.")

@mcp.tool()
def my_tool(query: str) -> str:
    """Tool description."""
    return do_something(query)

if __name__ == "__main__":
    mcp.run()
```

**2. Add the manifest**

```json
// my-plugin/plugin.json
{
  "name": "my-plugin",
  "version": "0.1.0",
  "description": "What it does",
  "type": "native",
  "module": "server",
  "mcp_attr": "mcp",
  "default": false
}
```

**3. Test**

```bash
# Standalone
python my-plugin/server.py

# Docked
cp -r my-plugin ~/.coreforged/plugins/
coreforged-mcp status
```

A template plugin is included at `src/coreforged_mcp/plugins/_template/`.

## Plugin Types

| Type | How It Works | Best For |
|------|-------------|----------|
| **Native** | Python module imported in-process | Python tools, zero overhead |
| **Proxy** | External process spawned, tools bridged via JSON-RPC | Node.js, Go, Rust servers |

## CLI Commands

| Command | What It Does |
|---------|-------------|
| `coreforged-mcp run` | Start the gateway server |
| `coreforged-mcp status` | Show discovered plugins and loadouts |
| `coreforged-mcp init` | Add CoreforgedMCP to `.mcp.json` |
| `coreforged-mcp install-plugin <path> [--key KEY]` | Install a plugin from a zip |

## Available Plugins

| Plugin | Source | What It Does |
|--------|--------|-------------|
| **KeyRing** | Bundled | Sovereign secrets — API keys never enter context |
| Digital Analytics | [coreforged.com](https://coreforged.com) | GA4 + Search Console + PageSpeed |
| SEO Bundle | [coreforged.com](https://coreforged.com) | Keyword research + SERP analysis |

## License

MIT — the gateway is free and open source. Some plugins on [coreforged.com](https://coreforged.com) are commercially licensed.

## Contributing

PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).

Built by [CoreForged LLC](https://coreforged.com).
