# Guardian Forge MCP Bridge Scripts

These scripts allow you to connect MCP clients (like Claude Desktop, Cursor, or Claude Code) to the Guardian Forge MCP server hosted on HuggingFace Spaces.

## Prerequisites

- Node.js 18+ (for native `fetch` API support)
- Guardian Forge API key (generate one from the Settings tab in your dashboard)

## Available Scripts

### 1. `guardian-forge-mcp-bridge.js` (Recommended)
Full-featured bridge with complete MCP protocol support including:
- JSON-RPC 2.0 protocol handling
- Tool listing via `tools/list`
- Tool execution via `tools/call`
- Proper initialization handshake
- Error handling

### 2. `guardian-forge-bridge.js`
Simple passthrough bridge for basic MCP operations.

## Setup

### Step 1: Get Your API Key

1. Visit https://mcp-1st-birthday-guardian-forge.hf.space
2. Sign in with Google
3. Go to **Settings** tab → **Application** sub-tab
4. Click **Generate New API Key**
5. Copy your API key (starts with `gf_`)

### Step 2: Set Environment Variable

**Windows (PowerShell):**
```powershell
$env:GUARDIAN_FORGE_API_KEY="gf_your_api_key_here"
```

**Windows (Command Prompt):**
```cmd
set GUARDIAN_FORGE_API_KEY=gf_your_api_key_here
```

**macOS/Linux (bash/zsh):**
```bash
export GUARDIAN_FORGE_API_KEY="gf_your_api_key_here"
```

To make it permanent, add to your shell profile:
```bash
# Add to ~/.bashrc or ~/.zshrc
export GUARDIAN_FORGE_API_KEY="gf_your_api_key_here"
```

### Step 3: Configure Your MCP Client

#### Claude Desktop

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

```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": [
        "/absolute/path/to/scripts/guardian-forge-mcp-bridge.js"
      ]
    }
  }
}
```

#### Claude Code

Edit `.vscode/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": [
        "/absolute/path/to/scripts/guardian-forge-mcp-bridge.js"
      ]
    }
  }
}
```

#### Cursor

Edit your Cursor MCP settings:

```json
{
  "mcpServers": {
    "guardian-forge": {
      "command": "node",
      "args": [
        "/absolute/path/to/scripts/guardian-forge-mcp-bridge.js"
      ]
    }
  }
}
```

## Testing the Connection

### Test the bridge directly:
```bash
# Echo a test request to the bridge
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | node guardian-forge-mcp-bridge.js
```

You should see a JSON response with server info.

### Check logs:
The bridge logs to stderr, so you can see connection status:
```
[Guardian Forge Bridge] Bridge started, connecting to Guardian Forge at https://mcp-1st-birthday-guardian-forge.hf.space (authenticated)
```

## Troubleshooting

### "No API key set" warning
- Make sure you've set the `GUARDIAN_FORGE_API_KEY` environment variable
- Restart your terminal/shell after setting the variable
- Verify the variable is set: `echo $GUARDIAN_FORGE_API_KEY` (Linux/macOS) or `echo %GUARDIAN_FORGE_API_KEY%` (Windows)

### HTTP 401 Unauthorized
- Your API key may be invalid or expired
- Generate a new API key from the dashboard
- Make sure the API key starts with `gf_`

### HTTP 403 Forbidden
- The tool you're trying to access may require approval
- Check the Approval Dashboard to approve pending tools

### Connection refused
- Check your internet connection
- Verify the HuggingFace Space is running: https://mcp-1st-birthday-guardian-forge.hf.space/health

### Tools not appearing
**Default State:** The server starts with only the `request_new_tool` bootstrap tool. This is normal!

**How to get more tools:**
1. Use `request_new_tool` to create your first tool in your MCP client
2. New tools require human approval in the dashboard at https://mcp-1st-birthday-guardian-forge.hf.space/admin
3. After approval, tools appear automatically (the server sends `notifications/tools/list_changed`)
4. Your MCP client should auto-refresh, or try disconnecting/reconnecting

**If you have approved tools but still don't see them:**
- Make sure you're authenticated with a valid API key
- Check the Approved Tools tab in the dashboard to verify tools exist
- Look for disabled projects - tools in disabled projects won't appear
- Try restarting your MCP client completely

## Server Information

- **Base URL**: https://mcp-1st-birthday-guardian-forge.hf.space
- **MCP Endpoint**: https://mcp-1st-birthday-guardian-forge.hf.space/mcp
- **Health Check**: https://mcp-1st-birthday-guardian-forge.hf.space/health
- **Authentication**: Bearer token in `Authorization` header

## Security Notes

- Never commit your API key to version control
- API keys are user-specific and grant full access to your Guardian Forge tools
- You can revoke API keys at any time from the Settings tab
- The bridge script reads the API key from an environment variable for security

## Advanced Usage

### Run without API key (public access)
Some tools may work without authentication:
```bash
unset GUARDIAN_FORGE_API_KEY  # Remove API key
node guardian-forge-mcp-bridge.js
```

### Custom MCP server URL
Edit the script to point to a different deployment:
```javascript
const GUARDIAN_FORGE_BASE_URL = 'https://your-custom-deployment.hf.space';
```

## Support

For issues or questions:
- Check the Guardian Forge dashboard logs
- Visit the HuggingFace Space discussion: https://huggingface.co/spaces/MCP-1st-Birthday/Guardian-Forge/discussions
- Review the application logs at: https://huggingface.co/spaces/MCP-1st-Birthday/Guardian-Forge/logs (space owners only)