Metadata-Version: 2.4
Name: coreforged-mcp
Version: 0.1.3
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: crypto
Requires-Dist: cryptography>=41.0; extra == "crypto"
Provides-Extra: keyring
Requires-Dist: coreforged-mcp[crypto]; extra == "keyring"
Provides-Extra: all
Requires-Dist: coreforged-mcp[crypto]; 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 — Free Secret Management

Your API keys never enter the conversation. Install it alongside the gateway:

```bash
pip install keyring-coreforged
keyring-coreforged  # registers with gateway
```

Secrets are encrypted at rest (Fernet/AES-128-CBC + HMAC-SHA256) with a machine-local master key. The keyring retrieves and decrypts the secret, makes the authenticated API call, and returns only the response data. Every checkout is logged. Outbound requests are restricted to an allowlist of known service domains.

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

Get KeyRing free at [coreforged.com/products/keyring](https://coreforged.com/products/keyring).

## 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 |
| `coreforged-mcp claim <shard>` | Claim an identity shard from your activation page |
| `coreforged-mcp scan [--dir DIR]` | Discover credentials in your filesystem |
| `coreforged-mcp consolidate [--dir DIR]` | Scan and load credentials onto your KeyRing |
| `coreforged-mcp allow-domain <domain>` | Add a domain to the KeyRing request allowlist |
| `coreforged-mcp list-domains` | Show all allowed domains |

## Available Plugins

| Plugin | Source | What It Does |
|--------|--------|-------------|
| **KeyRing** | [Free](https://coreforged.com/products/keyring) | 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).
