Metadata-Version: 2.4
Name: public-apis-mcp
Version: 0.1.0
Summary: MCP server exposing a catalog of free APIs with embedding-based lookups
Author-email: Alexander Galea <alex@galea.dev>
License: MIT License
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://pypi.org/project/public-apis-mcp/
Project-URL: Repository, https://github.com/zazencodes/public-apis-mcp
Project-URL: Changelog, https://github.com/zazencodes/public-apis-mcp/blob/main/CHANGELOG.md
Keywords: mcp,model context protocol,public,free,api,apis
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=2.10
Requires-Dist: pydantic>=2
Requires-Dist: numpy>=1.24
Requires-Dist: fastembed>=0.3.2
Dynamic: license-file

## Public APIs MCP

Catalog of free public APIs with semantic search.

## 🎯 Features

- `search_public_apis`: embedding-based search over API names and descriptions
- `get_public_api_details`: retrieve full details by `id`
- Resources: `public-apis://apis`, `public-apis://api/{id}`

## 🔧 Setup (uv)

Add to MCP clients (e.g., Claude Desktop) using uv.

### Claude Desktop

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "public-apis": {
      "command": "uvx",
      "args": ["public-apis-mcp"]
    }
  }
}
```

## 🚀 Usage

- Build embeddings index (optional; auto-build on first search):
```bash
uvx public-apis-mcp build-index
```
- Run the MCP server over STDIO:
```bash
uvx public-apis-mcp run
```

## 📋 Tool Reference

### `search_public_apis`
- Purpose: Semantic search over the catalog
- Parameters: `query` (str), `limit` (int, default 5)
- Returns: list of `{ id, name, score, snippet }`

Example call payload:
```json
{ "name": "search_public_apis", "arguments": { "query": "weather", "limit": 5 } }
```

### `get_public_api_details`
- Purpose: Fetch full details by `id`
- Parameters: `id` (str)
- Returns: `ApiItem`

Example call payload:
```json
{ "name": "get_public_api_details", "arguments": { "id": "a6b3a6b3-a6b3-a6b3-a6b3-a6b3a6b3a6b3" } }
```

## 🛠️ Development

Prerequisites:
- Python 3.10+
- uv (`https://docs.astral.sh/uv/`)

Setup:
```bash
uv sync --dev
```

Run tests:
```bash
FREE_APIS_MCP_TEST_MODE=1 uv run pytest -q
```

Lint and format:
```bash
uv run ruff check --fix
uv run ruff format
```

Type checking:
```bash
uv run mypy src/
```

### MCP Client Dev Config

```json
{
  "mcpServers": {
    "public-apis-dev": {
      "command": "uv",
      "args": [
        "--directory",
        "<abs_path>/public-apis-mcp",
        "run",
        "public-apis-mcp"
      ]
    }
  }
}
```

### Build and Try

```bash
uv build
uv run --with dist/*.whl public-apis-mcp --help
```


## 📦 Data & Index

- Data: `src/public_apis_mcp/datastore/free_apis.json`
- Embedding index: `src/public_apis_mcp/datastore/index.npz` (auto-built)

## Testing with MCP Inspector

For exploring and/or developing this server, use the MCP Inspector npm utility:

```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run local development server with the inspector
npx @modelcontextprotocol/inspector uv run public-apis-mcp

# Run PyPI production server with the inspector
npx @modelcontextprotocol/inspector uvx public-apis-mcp
```


## 📝 License

MIT License - see [LICENSE](LICENSE) file for details.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

