agentrank-mcp 0.1.0__tar.gz

agentrank_mcp-0.1.0/LISTING.md

@@ -0,0 +1,40 @@
+# Ficha de listagem — AgentRank MCP (copiar/colar nos registros)
+
+**Nome:** AgentRank — Real Business Index
+**Slug/pacote:** agentrank-mcp
+**Uma linha (≤80 char):** Find real, verifiable businesses with provenance — for AI agents.
+
+**Descrição curta (≤200 char):**
+An MCP server that lets your agent search a verified index of real businesses (Brazil,
+US, Europe) and read profiles with source URLs — so it never invents phone numbers or
+addresses.
+
+**Descrição longa:**
+AgentRank is an agent-first index of real, verifiable businesses. Every result carries
+its source URL and a trust score, so agents can act on facts instead of hallucinations.
+This MCP server exposes two tools — `search_businesses` (natural-language search) and
+`get_business_profile` (contacts, location, hours, evidence). Free self-service key at
+agentsafepath.com. ~2.7M businesses and growing, covering Brazil, the US (SEC EDGAR) and
+Europe (GLEIF).
+
+**Categorias/tags:** business, search, data, verification, local-search, companies,
+provenance, agents, index
+
+**Ferramentas:**
+- `search_businesses(intent, limit=10)` — busca por intenção em linguagem natural.
+- `get_business_profile(company_id)` — perfil completo com proveniência.
+
+**Config necessária:** `AGENTRANK_API_KEY` (grátis em https://agentsafepath.com/registrar.html)
+
+**Prompts de exemplo:**
+- "Find a pharmacy in Copacabana, Rio, with a phone number."
+- "List software companies in California."
+- "Hotel em São Paulo com WhatsApp."
+
+**Links:**
+- Site: https://agentsafepath.com
+- Registro de agente: https://agentsafepath.com/registrar.html
+- API docs (agent-readable): https://api.agentrank.intelligenceofcode.com/api/agent/docs
+- Termos: https://api.agentrank.intelligenceofcode.com/api/agent/terms
+
+**Licença:** MIT (servidor MCP). Dados sob licenças das fontes (CC0/públicas).

agentrank_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: agentrank-mcp
+Version: 0.1.0
+Summary: MCP server for AgentRank / AgentIndex — search real, verifiable businesses for AI agents.
+Author: AgentRank
+License: MIT
+Keywords: agentrank,agents,business,index,mcp
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# AgentRank MCP server
+
+Give your AI agent access to **real, verifiable businesses** — with provenance and
+source URLs, so it never invents phone numbers or addresses.
+
+This is an [MCP](https://modelcontextprotocol.io) server that exposes the
+[AgentRank / AgentIndex](https://agentsafepath.com) search to any MCP client
+(Claude Desktop, Cursor, and others).
+
+## Tools
+
+- **`search_businesses(intent, limit=10)`** — find businesses by a natural-language
+  intent (e.g. `"farmácia em Copacabana com telefone"`, `"software company in California"`).
+  Returns ranked results with `fit_score`, `trust_score`, justification, risks and the
+  **source URL** of each fact.
+- **`get_business_profile(company_id)`** — full profile of a result: location, contact
+  channels, hours, offers, policies and evidence, each with provenance and source.
+
+## 1. Get an API key
+
+Register your agent (free, no invite) at
+**https://agentsafepath.com/registrar.html** — you receive a key once. It identifies
+your agent and is sent as `Authorization: Bearer <key>`.
+
+## 2. Add it to your MCP client
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config) and add:
+
+```json
+{
+  "mcpServers": {
+    "agentrank": {
+      "command": "uvx",
+      "args": ["agentrank-mcp"],
+      "env": { "AGENTRANK_API_KEY": "ak_your_key_here" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see `search_businesses` and `get_business_profile`
+available. (`uvx` comes with [uv](https://docs.astral.sh/uv/); or use the "From source"
+option below.)
+
+### Cursor
+
+Add the same block under `mcpServers` in your Cursor MCP settings.
+
+### From source (no packaging)
+
+```bash
+pip install -r requirements.txt
+AGENTRANK_API_KEY=ak_your_key_here python -m agentrank_mcp.server
+```
+
+And point your client's `command` at `python` with `args`
+`["-m", "agentrank_mcp.server"]` and the folder on `PYTHONPATH`.
+
+## Environment variables
+
+| Var | Required | Default |
+|---|---|---|
+| `AGENTRANK_API_KEY` | yes | — |
+| `AGENTRANK_BASE_URL` | no | `https://api.agentrank.intelligenceofcode.com` |
+
+The key is never logged.
+
+## How agents should use the data
+
+Every result carries `sources` (source URLs). **Verify provenance before acting** —
+data without a source should not be used. `trust_score` (0–100) reflects how safe the
+entity is to commit to; `fit_score` reflects match to the intent.

agentrank_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,71 @@
+# Publicar o AgentRank MCP (passo a passo)
+
+Objetivo: fazer o servidor ser **descoberto** — publicando no PyPI (para `uvx
+agentrank-mcp` funcionar) e no **registro oficial de MCP** (de onde agregadores como
+PulseMCP e Glama puxam automaticamente).
+
+> Substitua `SEU_USUARIO_GITHUB` pelo seu usuário do GitHub em todos os lugares.
+> O nome no registro será `io.github.SEU_USUARIO_GITHUB/agentrank-mcp` — por isso o
+> repo precisa estar no SEU GitHub (a autenticação prova que o namespace é seu).
+
+## 1. Repositório no GitHub
+```bash
+cd agentrank-mcp
+git init && git add -A && git commit -m "AgentRank MCP server 0.1.0"
+git branch -M main
+git remote add origin https://github.com/SEU_USUARIO_GITHUB/agentrank-mcp.git
+git push -u origin main
+```
+
+## 2. Publicar no PyPI (habilita `uvx agentrank-mcp`)
+Precisa de conta em https://pypi.org e um token de API (Account settings → API tokens).
+```bash
+cd agentrank-mcp
+python -m pip install --upgrade build twine
+python -m build                 # gera dist/*.whl e dist/*.tar.gz
+python -m twine upload dist/*    # usuário: __token__  | senha: seu token pypi-...
+```
+Verifique em https://pypi.org/project/agentrank-mcp/ . A partir daqui, qualquer um
+roda `uvx agentrank-mcp` (com AGENTRANK_API_KEY no ambiente).
+
+## 3. Publicar no registro oficial de MCP
+O registro guarda só metadados; o pacote (passo 2) precisa existir antes.
+
+Instale o CLI:
+```bash
+# macOS/Linux (Homebrew): brew install mcp-publisher
+# ou baixe o binario da release em github.com/modelcontextprotocol/registry
+```
+Gere e edite o `server.json` (já deixei um pronto neste repo — ajuste SEU_USUARIO_GITHUB
+e a versão):
+```bash
+mcp-publisher init      # gera/atualiza server.json a partir do projeto
+# confira: name = io.github.SEU_USUARIO_GITHUB/agentrank-mcp ; packages[0].registryType = "pypi"
+```
+> Validação de posse (PyPI): o registro confere que o pacote é seu. Se o `publish`
+> reclamar de "validation failed for package", siga a página oficial de tipos de
+> pacote (https://modelcontextprotocol.io/registry/package-types) — ela indica o campo
+> de verificação a incluir no pacote PyPI. O `mcp-publisher init` costuma já preparar isso.
+
+Autentique e publique:
+```bash
+mcp-publisher login github     # abre github.com/login/device, cole o código
+mcp-publisher publish
+curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=agentrank"
+```
+
+## 4. Agregadores (automático + submissão)
+- **PulseMCP** (https://www.pulsemcp.com) e **Glama** (https://glama.ai/mcp/servers)
+  indexam servidores públicos do GitHub / registro oficial. Depois dos passos 1–3, eles
+  tendem a listar sozinhos; se houver formulário de "submit server", informe a URL do
+  repo GitHub + a descrição do LISTING.md.
+
+## 5. Smithery (opcional — servidor stdio local = bundle MCPB)
+Para stdio local, o Smithery distribui um **bundle MCPB** (não `smithery.yaml`):
+1. Gere um `.mcpb` do servidor (guia: https://claude.com/docs/connectors/building/mcpb).
+2. Em https://smithery.ai/new, escolha "Local (MCPB Bundle)" e publique o bundle.
+É mais trabalhoso; priorize PyPI + registro oficial (passos 2–3), que já dão descoberta.
+
+## 6. Anúncio
+Use o `LAUNCH_POST.md` (na raiz do projeto): Show HN, Reddit r/mcp, dev.to e X.
+E adicione o link do MCP na landing (`desenvolvedores.html`).

agentrank_mcp-0.1.0/README.md

@@ -0,0 +1,74 @@
+# AgentRank MCP server
+
+Give your AI agent access to **real, verifiable businesses** — with provenance and
+source URLs, so it never invents phone numbers or addresses.
+
+This is an [MCP](https://modelcontextprotocol.io) server that exposes the
+[AgentRank / AgentIndex](https://agentsafepath.com) search to any MCP client
+(Claude Desktop, Cursor, and others).
+
+## Tools
+
+- **`search_businesses(intent, limit=10)`** — find businesses by a natural-language
+  intent (e.g. `"farmácia em Copacabana com telefone"`, `"software company in California"`).
+  Returns ranked results with `fit_score`, `trust_score`, justification, risks and the
+  **source URL** of each fact.
+- **`get_business_profile(company_id)`** — full profile of a result: location, contact
+  channels, hours, offers, policies and evidence, each with provenance and source.
+
+## 1. Get an API key
+
+Register your agent (free, no invite) at
+**https://agentsafepath.com/registrar.html** — you receive a key once. It identifies
+your agent and is sent as `Authorization: Bearer <key>`.
+
+## 2. Add it to your MCP client
+
+### Claude Desktop
+
+Edit `claude_desktop_config.json` (Settings → Developer → Edit Config) and add:
+
+```json
+{
+  "mcpServers": {
+    "agentrank": {
+      "command": "uvx",
+      "args": ["agentrank-mcp"],
+      "env": { "AGENTRANK_API_KEY": "ak_your_key_here" }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see `search_businesses` and `get_business_profile`
+available. (`uvx` comes with [uv](https://docs.astral.sh/uv/); or use the "From source"
+option below.)
+
+### Cursor
+
+Add the same block under `mcpServers` in your Cursor MCP settings.
+
+### From source (no packaging)
+
+```bash
+pip install -r requirements.txt
+AGENTRANK_API_KEY=ak_your_key_here python -m agentrank_mcp.server
+```
+
+And point your client's `command` at `python` with `args`
+`["-m", "agentrank_mcp.server"]` and the folder on `PYTHONPATH`.
+
+## Environment variables
+
+| Var | Required | Default |
+|---|---|---|
+| `AGENTRANK_API_KEY` | yes | — |
+| `AGENTRANK_BASE_URL` | no | `https://api.agentrank.intelligenceofcode.com` |
+
+The key is never logged.
+
+## How agents should use the data
+
+Every result carries `sources` (source URLs). **Verify provenance before acting** —
+data without a source should not be used. `trust_score` (0–100) reflects how safe the
+entity is to commit to; `fit_score` reflects match to the intent.

agentrank_mcp-0.1.0/agentrank_mcp/__init__.py

@@ -0,0 +1,2 @@
+"""AgentRank MCP server package."""
+__version__ = "0.1.0"

agentrank_mcp-0.1.0/agentrank_mcp/server.py

@@ -0,0 +1,142 @@
+"""Servidor MCP do AgentRank / AgentIndex.
+
+Expõe o índice agent-first de empresas reais e verificáveis como ferramentas MCP,
+para que qualquer agente (Claude Desktop, Cursor, etc.) possa buscar empresas e ler
+perfis com proveniência — sem inventar dados.
+
+Configuração por variáveis de ambiente:
+    AGENTRANK_API_KEY   (obrigatória)  -> chave do agente (Authorization: Bearer)
+    AGENTRANK_BASE_URL  (opcional)     -> padrão https://api.agentrank.intelligenceofcode.com
+
+A chave NUNCA é logada. Obtenha a sua em https://agentsafepath.com/registrar.html
+"""
+from __future__ import annotations
+
+import os
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+BASE_URL = os.environ.get(
+    "AGENTRANK_BASE_URL", "https://api.agentrank.intelligenceofcode.com"
+).rstrip("/")
+API_KEY = os.environ.get("AGENTRANK_API_KEY", "").strip()
+USER_AGENT = "agentrank-mcp/0.1"
+
+mcp = FastMCP("agentrank")
+
+
+def _headers() -> dict:
+    h = {"User-Agent": USER_AGENT, "Content-Type": "application/json"}
+    if API_KEY:
+        h["Authorization"] = f"Bearer {API_KEY}"
+    return h
+
+
+def _need_key_msg() -> dict:
+    return {
+        "error": "missing_api_key",
+        "message": (
+            "Defina AGENTRANK_API_KEY no ambiente do servidor MCP. "
+            "Cadastre seu agente em https://agentsafepath.com/registrar.html para obter uma."
+        ),
+    }
+
+
+@mcp.tool()
+def search_businesses(intent: str, limit: int = 10) -> dict:
+    """Busca empresas reais e verificáveis por uma intenção em linguagem natural.
+
+    Use quando o usuário quiser encontrar um negócio (ex.: "farmácia em Copacabana
+    com telefone", "hotel em São Paulo", "software company in California"). Retorna
+    empresas ranqueadas com fit_score, trust_score, justificativa, riscos e as FONTES
+    (source_url) de cada dado — verifique a proveniência antes de agir. Nunca invente
+    telefone, endereço ou e-mail: use apenas o que vier nas fontes.
+
+    Args:
+        intent: a intenção em linguagem natural (ex.: "restaurante em Pinheiros").
+        limit: número máximo de resultados (1 a 50; padrão 10).
+    """
+    if not API_KEY:
+        return _need_key_msg()
+    limit = max(1, min(int(limit or 10), 50))
+    try:
+        r = httpx.post(
+            f"{BASE_URL}/api/agent/search",
+            headers=_headers(),
+            json={"intent": intent, "limit": limit},
+            timeout=30,
+        )
+    except httpx.HTTPError as exc:
+        return {"error": "connection", "message": str(exc)[:200]}
+    if r.status_code == 401:
+        return {"error": "unauthorized", "message": "Chave inválida ou ausente."}
+    if r.status_code == 429:
+        return {"error": "rate_limited",
+                "message": "Limite de uso atingido. Tente novamente mais tarde.",
+                "retry_after": r.headers.get("Retry-After")}
+    if r.status_code != 200:
+        return {"error": f"http_{r.status_code}", "message": r.text[:200]}
+    body = r.json()
+    recs = body.get("recommendations", [])
+    return {
+        "intent": body.get("intent", intent),
+        "results_count": body.get("results_count", len(recs)),
+        "query_id": body.get("query_id"),
+        "warnings": body.get("warnings", []),
+        "results": [
+            {
+                "company_id": rec.get("company_id"),
+                "name": rec.get("name"),
+                "domain": rec.get("domain"),
+                "category": rec.get("category"),
+                "region": rec.get("region"),
+                "fit_score": rec.get("fit_score"),
+                "trust_score": rec.get("trust_score"),
+                "justification": rec.get("justification"),
+                "risks": rec.get("risks", []),
+                "sources": rec.get("sources", []),
+            }
+            for rec in recs
+        ],
+        "note": "Verifique as 'sources' (source_url) antes de agir. Dados sem fonte não devem ser usados.",
+    }
+
+
+@mcp.tool()
+def get_business_profile(company_id: int) -> dict:
+    """Retorna o perfil completo de uma empresa (por company_id de uma busca anterior).
+
+    Traz localização, canais de contato, horários, ofertas, políticas e evidências —
+    cada afirmação com proveniência e source_url. Use para obter o telefone/endereço
+    verificável de um resultado antes de agir sobre ele.
+
+    Args:
+        company_id: o id retornado por search_businesses.
+    """
+    if not API_KEY:
+        return _need_key_msg()
+    try:
+        r = httpx.get(
+            f"{BASE_URL}/api/agents/company/{int(company_id)}.json",
+            headers=_headers(),
+            timeout=30,
+        )
+    except httpx.HTTPError as exc:
+        return {"error": "connection", "message": str(exc)[:200]}
+    if r.status_code == 401:
+        return {"error": "unauthorized", "message": "Chave inválida ou ausente."}
+    if r.status_code == 404:
+        return {"error": "not_found", "message": f"Empresa {company_id} não encontrada."}
+    if r.status_code != 200:
+        return {"error": f"http_{r.status_code}", "message": r.text[:200]}
+    return r.json()
+
+
+def main() -> None:
+    """Ponto de entrada (stdio). Usado por 'uvx agentrank-mcp' ou 'python -m agentrank_mcp.server'."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

agentrank_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,23 @@
+[project]
+name = "agentrank-mcp"
+version = "0.1.0"
+description = "MCP server for AgentRank / AgentIndex — search real, verifiable businesses for AI agents."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "AgentRank" }]
+keywords = ["mcp", "agents", "business", "index", "agentrank"]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27",
+]
+
+[project.scripts]
+agentrank-mcp = "agentrank_mcp.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["agentrank_mcp"]

agentrank_mcp-0.1.0/requirements.txt

@@ -0,0 +1,2 @@
+mcp>=1.2.0
+httpx>=0.27

agentrank_mcp-0.1.0/server.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.SEU_USUARIO_GITHUB/agentrank-mcp",
+  "description": "Search real, verifiable businesses (Brazil, US, Europe) with provenance and source URLs — for AI agents.",
+  "repository": {
+    "url": "https://github.com/SEU_USUARIO_GITHUB/agentrank-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "agentrank-mcp",
+      "version": "0.1.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "AGENTRANK_API_KEY",
+          "description": "Your AgentRank agent API key (register at https://agentsafepath.com/registrar.html).",
+          "isRequired": true,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "AGENTRANK_BASE_URL",
+          "description": "API base URL (optional).",
+          "isRequired": false,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}