# Community Registry

Share, discover, and install capability definitions from the community.

## Installing Capabilities

### From the Built-in Registry

All 110+ built-in capabilities ship with mcp-gateway. The exact tracked inventory is currently 119 YAMLs. Browse what is available:

```bash
# List everything
mcp-gateway cap registry-list

# Search by keyword
mcp-gateway cap search weather
mcp-gateway cap search finance
```

### From GitHub

Install a capability from any GitHub repository that follows the standard layout:

```bash
# Install from the official repository
mcp-gateway cap install stock_quote --from-github

# Install from a community repository
mcp-gateway cap install my_tool --from-github --repo owner/repo

# Install from a specific branch
mcp-gateway cap install my_tool --from-github --repo owner/repo --branch develop

# Install to a custom directory
mcp-gateway cap install my_tool --from-github --output ./my-capabilities
```

The installer looks for capability YAMLs in category subdirectories within the repository's `capabilities/` directory.

## Check for shadow MCP servers before adopting more tools

Before adding community tools on a workstation with existing AI clients, run:

```bash
mcp-gateway cap discover --shadow --format json
```

The ShadowRadar report groups unmanaged MCP servers by actionability, not only
severity. Each finding has a stable ID, data-risk classification, recommended
action, confidence, confirmation requirement, verification step, and rollback
step. The scanner is passive by default and never invokes discovered tools.
Use `--write-config` only after reviewing adoptable local findings.

## Creating a Capability

### YAML Template

Every capability is a single YAML file following the Fulcrum 1.0 schema:

```yaml
fulcrum: "1.0"
name: your_capability_name
description: Short, clear description of what this capability does

schema:
  input:
    type: object
    properties:
      param1:
        type: string
        description: What this parameter controls
      param2:
        type: number
        description: Numeric value for something
    required: [param1]
  output:
    type: object
    properties:
      result:
        type: string

providers:
  primary:
    service: rest
    cost_per_call: 0
    timeout: 30
    config:
      base_url: https://api.example.com
      path: /v1/endpoint
      method: GET
      params:
        q: "{param1}"
        limit: "{param2}"

cache:
  strategy: exact
  ttl: 300

auth:
  required: false
  # If auth is required:
  # required: true
  # type: bearer        # or api_key, oauth2
  # key: env:API_TOKEN  # environment variable reference
  # description: "Get your API key at https://example.com/keys"

metadata:
  category: utility     # knowledge, search, finance, geo, entertainment, communication, food, utility
  tags: [tag1, tag2]
  cost_category: free   # free, cheap, paid
  execution_time: fast  # fast, medium, slow
  read_only: true       # true for GET/HEAD, false for mutations
```

### Required Fields

| Field | Description |
|-------|-------------|
| `fulcrum` | Schema version, always `"1.0"` |
| `name` | Unique snake_case identifier |
| `description` | What the capability does (shown in search results) |
| `schema.input` | JSON Schema for parameters the AI provides |
| `providers.primary` | At least one provider with service type and config |
| `auth` | Whether authentication is required |
| `metadata.category` | One of the standard categories |

### Validate Before Sharing

```bash
mcp-gateway cap validate your_capability.yaml
```

This checks all required fields, schema validity, and provider configuration.

### Test Locally

```bash
mcp-gateway cap test your_capability.yaml --args '{"param1": "test"}'
```

## Sharing via GitHub

### Repository Layout

Your repository should place capabilities under `capabilities/<category>/`:

```
your-repo/
  capabilities/
    finance/
      my_stock_tool.yaml
    utility/
      my_converter.yaml
  README.md
```

This layout is required for `mcp-gateway cap install --from-github` to find your capabilities automatically.

### Step-by-Step

1. **Create** your capability YAML and validate it locally.

2. **Organize** it under the correct category directory:
   ```bash
   mkdir -p capabilities/utility
   cp my_tool.yaml capabilities/utility/
   ```

3. **Push** to a public GitHub repository.

4. **Test** the install flow:
   ```bash
   mcp-gateway cap install my_tool --from-github --repo your-username/your-repo
   ```

5. **Share** the install command with others:
   ```
   mcp-gateway cap install my_tool --from-github --repo your-username/your-repo
   ```

## Submitting to the Official Registry

The official registry lives in the [MikkoParkkola/mcp-gateway](https://github.com/MikkoParkkola/mcp-gateway) repository under `capabilities/`.

### Submission Criteria

- Capability must validate: `mcp-gateway cap validate your_capability.yaml`
- Capability must test successfully: `mcp-gateway cap test your_capability.yaml --args '{...}'`
- Free-tier or zero-config APIs are preferred (no paid-only capabilities)
- Name must be unique (check with `mcp-gateway cap search your_name`)
- Description must be clear and concise
- Correct `metadata.category` and meaningful `tags`
- `auth.description` must include signup URL if a key is required

### Pull Request Process

1. **Fork** the repository on GitHub.

2. **Add** your capability YAML to the correct category:
   ```bash
   cp my_tool.yaml capabilities/<category>/
   ```

3. **Validate** the full registry still loads:
   ```bash
   mcp-gateway cap list capabilities/
   ```

4. **Open a PR** with:
   - Title: `cap: add <capability_name>`
   - Description: what the API does, free tier details, example usage
   - The `mcp-gateway cap test` output demonstrating it works

5. **CI checks** will verify:
   - YAML parses correctly
   - Schema validation passes
   - No duplicate names

### Example PR Description

```markdown
## Add `openweathermap_forecast` capability

**API**: OpenWeatherMap One Call 3.0
**Free tier**: 1,000 calls/day
**Auth**: API key (free signup at openweathermap.org)

### Test output
$ mcp-gateway cap test capabilities/knowledge/openweathermap_forecast.yaml \
    --args '{"lat": 60.17, "lon": 24.94}'
Success:
{
  "temp": 5.2,
  "description": "partly cloudy"
}
```

## Categories Reference

| Category | Directory | Use For |
|----------|-----------|---------|
| `knowledge` | `capabilities/knowledge/` | Reference data, facts, geocoding, academic |
| `search` | `capabilities/search/` | Web, news, images, code search |
| `finance` | `capabilities/finance/` | Stock quotes, currency, filings, company data |
| `geo` | `capabilities/geo/` | IP geolocation, mapping |
| `entertainment` | `capabilities/entertainment/` | Movies, music, jokes, trivia |
| `utility` | `capabilities/utility/` | QR codes, UUIDs, mock data, tracking |
| `communication` | `capabilities/communication/` | Email, messaging |
| `food` | `capabilities/food/` | Nutrition, recipes |
