Metadata-Version: 2.4
Name: mcp-fingerprints
Version: 1.0.2
Summary: Open-Source MCP Server Passport & Tool Signature Knowledge Base
Author: MCP Fingerprints Contributors
License: MIT
Project-URL: Homepage, https://jmartynov.github.io/mcp-fingerprints/
Project-URL: Repository, https://github.com/JMartynov/mcp-fingerprints
Project-URL: Issues, https://github.com/JMartynov/mcp-fingerprints/issues
Keywords: mcp,model-context-protocol,security,fingerprints,ai-agents,llm
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Topic :: Security
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: packaging>=24.0
Requires-Dist: pyyaml>=6.0.3
Requires-Dist: tenacity>=8.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pyyaml; extra == "dev"
Provides-Extra: semantic
Requires-Dist: fastembed>=0.3.0; extra == "semantic"
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.0.0; extra == "duckdb"

# MCP Fingerprints & Passport Knowledge Base

[![Daily MCP Fingerprint & Passport Sync](https://github.com/JMartynov/mcp-fingerprints/actions/workflows/daily_sync.yml/badge.svg)](https://github.com/JMartynov/mcp-fingerprints/actions/workflows/daily_sync.yml)
[![Passports Count](https://img.shields.io/badge/passports-5058+-blue.svg)](data/fingerprints)
[![Tools Provided](https://img.shields.io/badge/with_tools-710-green.svg)](data/fingerprints)
[![Tombstoned Servers](https://img.shields.io/badge/tombstoned-150-inactive.svg)](data/fingerprints)
[![Test Suite](https://img.shields.io/badge/tests-252_passing-brightgreen.svg)](tests/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Web Directory](https://img.shields.io/badge/Web_Directory-Live_Catalog-38bdf8?style=flat-square&logo=googlechrome)](https://jmartynov.github.io/mcp-fingerprints/)
[![What's New](https://img.shields.io/badge/What's_New-Latest_Sync_Updates-22c55e?style=flat-square&logo=git)](https://jmartynov.github.io/mcp-fingerprints/updates.html)

An open-source, automated database and knowledge base of **Model Context Protocol (MCP)** server passports, version signatures, and tool contract fingerprints.

## Ecosystem Architecture & Scope

`mcp-fingerprints` serves as the authoritative open standard for structural Model Context Protocol server passports. It focuses purely on:
* **Static AST Extraction**: Deep parameter schema, docstring, prompt, and resource extraction across Python, TypeScript/JavaScript, Go, and Rust.
* **Deterministic Cryptographic Hashing**: Order-invariant and whitespace-insensitive canonical hashing (`canonical_hash`, `toolset_canonical_hash`).
* **Supply-Chain Verification & Drift Tracking**: Detecting tool tampering, description changes, and schema mutations across package versions.
* **Open Catalog & Client Exporters**: Serving enriched structural web catalogs with interactive parameter schema inspectors and 1-click config generators.

## Key Features
- **5,058+ Indexed Passports**: Cross-indexed across Smithery, npm, PyPI, and GitHub registries.
- **Deep Parameter & Annotation Extraction**: Captures parameter types, descriptions, defaults, enums, required flags, and protocol annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`).
- **Automated Daily Sync**: Continuously crawls, extracts tool signatures, canonicalizes hash fingerprints, and tracks historical schema drift.
- **Consolidated Snapshot**: Pre-compiled `passports.json.gz` for rapid HTTP consumption (< 50ms startup time).

## Quickstart: Search & Client Export

Search for available MCP servers:
```bash
python3 -m mcp_fingerprints.cli search "postgres"
```

Export an MCP server configuration for Claude Desktop:
```bash
python3 -m mcp_fingerprints.cli export-config @modelcontextprotocol/server-postgres --client claude
```

Export an MCP server configuration for Cursor:
```bash
python3 -m mcp_fingerprints.cli export-config @modelcontextprotocol/server-postgres --client cursor
```

## Live Probing, Workstation Inventory & Drift Tracking

### The Problem It Solves
Developers, SecOps analysts, and platform engineers often have dozens of MCP servers configured across Claude Desktop, Cursor, and Windsurf, or connecting AI agents to remote HTTP/SSE endpoints. Over time, teams lose track of:
- **Identity & Provenance**: What exact software package is running behind a command or URL, and where was it downloaded from?
- **Shadow MCP Assets**: Which MCP servers are quietly installed in developer configuration files?
- **Silent Contract Drift**: Did an automated package upgrade change tool descriptions or inject new parameters without notice?

`mcp-fingerprints` provides a complete detection and inventory suite available as both a **CLI tool** and an **importable Python SDK**.

### 1. Workstation MCP Inventory (`scan-configs`)
Automatically discovers configuration files across Claude Desktop (`claude_desktop_config.json`), Cursor (global `~/.cursor/mcp.json` and project `.cursor/mcp.json`), and Windsurf, probes active servers, and determines their identities:

```bash
# Auto-discover and audit all local MCP configurations
mcp-fingerprints scan-configs --auto

# Export a consolidated JSON schema inventory of all local MCP tools
mcp-fingerprints scan-configs --auto --output mcp-inventory.json
```

**Python SDK:**
```python
from mcp_fingerprints import scan_local_configs

inventory = scan_local_configs(probe_live=True)
for server in inventory.servers:
    print(f"[{server.client_name}] {server.server_name}: {server.package_name} ({server.version})")
    print(f"  Tools: {', '.join(t.name for t in server.tools)}")
```

### 2. Stateful Run-to-Run Drift Tracking (`--compare-snapshot`)
Establish a baseline snapshot of your local MCP tools and catch unauthorized modifications, deleted servers, or drifted tool contracts:

```bash
# 1. Save an initial baseline snapshot
mcp-fingerprints scan-configs --auto --save-snapshot mcp-baseline.json

# 2. Check for drift on subsequent runs (or in CI/CD pre-commit hooks)
mcp-fingerprints scan-configs --auto --compare-snapshot mcp-baseline.json --fail-on-drift
```

**Sample Differential Drift Output:**
```text
======================================================================
               LOCAL MCP INVENTORY DRIFT REPORT
======================================================================
➕ ADDED SERVERS (1):
  • [Cursor] github-tools -> @modelcontextprotocol/server-github (v0.6.0)

🔄 MODIFIED / DRIFTED SERVERS (1):
  • [Claude] postgres -> @modelcontextprotocol/server-postgres
    - Version: 0.6.1 -> 0.6.2 (Upgraded)
    - Tool Contract Mutations:
      * 'read_query': Parameter 'timeout_ms' added (type: integer, optional)
======================================================================
```

### 3. Dual-Transport Live Probing & Attribution (`stdio` + `http`)
Connect to any live MCP server via local subprocess (`stdio`) or remote URL (`http`/`sse`), identify what it is, and retrieve its official repository and download instructions:

```bash
# Probe local server with concise 3-line summary
mcp-fingerprints probe --format short -- npx -y @modelcontextprotocol/server-postgres postgresql://localhost/db

# Probe remote HTTP/SSE endpoint
mcp-fingerprints probe --url http://localhost:8000/sse --format long

# Authenticated remote endpoint
mcp-fingerprints probe --url https://api.example.com/mcp --header "Authorization: Bearer mytoken"
```

**Python SDK:**
```python
from mcp_fingerprints import identify_stdio, identify_http

# Identify local subprocess
report = identify_stdio(["uvx", "mcp-server-git"])
print(f"Verified: {report.package_name} ({report.repository_url})")

# Identify remote HTTP/SSE endpoint
remote = identify_http("https://mcp.internal.acme.com/sse")
print(f"Remote Server: {remote.package_name} v{remote.version}")
```

## Enriched Tool Parameter Schemas & Protocol Annotations

MCP Fingerprints extracts rich parameter schemas and runtime protocol hints directly from server source ASTs:
* **Structured Parameter Metadata**: Includes parameter types (`string`, `number`, `boolean`, `array`, `object`), descriptions, required status, default values, and allowed enums.
* **Protocol Annotations**: Captures MCP tool behavior hints:
  - `readOnlyHint`: Tool performs read-only operations without side effects.
  - `destructiveHint`: Tool performs destructive operations (deletions, modifications).
  - `idempotentHint`: Repeated invocations yield identical state.
  - `openWorldHint`: Tool interacts with external/unconstrained network services.
* **Transport Specifications**: Captures supported transports (`stdio`, `sse`, `streamable-http`, `websocket`) and required environment variables.

## Fast Consumption

You can fetch the latest consolidated database in a single GET request:
```bash
curl -sL https://raw.githubusercontent.com/JMartynov/mcp-fingerprints/main/passports.json.gz | gzip -d > passports.json
```

### Python
```python
import gzip, json, urllib.request

url = "https://raw.githubusercontent.com/JMartynov/mcp-fingerprints/main/passports.json.gz"
with urllib.request.urlopen(url) as resp:
    with gzip.GzipFile(fileobj=resp) as gz:
        data = json.load(gz)

print(f"Loaded {data['total_passports']} MCP server passports.")
```

## CLI Usage

The CLI provides a focused set of pure structural commands:

```bash
# Sync from registries
python -m mcp_fingerprints.cli sync --all

# Match a toolset hash against the knowledge base
python -m mcp_fingerprints.cli match <hash>

# Probe a server and extract its fingerprint
python -m mcp_fingerprints.cli probe <server_command>

# Validate schema invariants
python -m mcp_fingerprints.cli validate --dir data/fingerprints

# Build compressed snapshot
python -m mcp_fingerprints.cli snapshot

# Search the catalog
python -m mcp_fingerprints.cli search "query"

# Browse interactively via TUI
python -m mcp_fingerprints.cli browse

# Export client configurations (Claude, Cursor, Cline, Zed, Windsurf)
python -m mcp_fingerprints.cli export-config <server_name> --client claude

# Detect configuration drift against the latest passports
python -m mcp_fingerprints.cli detect-drift <config_file>
```

## Reporting & Output Formats

Customize the output verbosity to fit your terminal or CI environment:

```bash
# Concise 3-line summary for quick checks and CI logs
mcp-fingerprints probe --format short -- npx -y @modelcontextprotocol/server-sqlite --db app.db

# Exhaustive schema and parameter audit report
mcp-fingerprints probe --format long -- npx -y @modelcontextprotocol/server-sqlite --db app.db

# Structured JSON output for scripting and automation
mcp-fingerprints probe --json -- npx -y @modelcontextprotocol/server-sqlite --db app.db
```

## Releases

### TestPyPI Dry-Run

You can perform an automated dry-run release to TestPyPI to verify packaging, metadata, and functionality before a production PyPI release.
1. Navigate to the **Actions** tab in the GitHub repository.
2. Select the **Release to TestPyPI (Dry-Run)** workflow.
3. Click **Run workflow**.
4. You can optionally provide a `version_suffix` (e.g. `rc1`, `b2`) which will be appended to the current version in `pyproject.toml` to avoid conflicts on TestPyPI.
5. The workflow will build artifacts, publish them to TestPyPI using Trusted Publishing, and execute an automated smoke test (`pip install` into a clean container).

## License
MIT
