wayforth-mcp 0.1.0__tar.gz

wayforth_mcp-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.pyd
+.venv/
+*.egg-info/
+dist/
+build/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Environment
+.env
+
+# Node
+node_modules/
+
+# Docker volumes
+docker/volumes/
+
+# IDE
+.cursor/
+.vscode/
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db

wayforth_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,71 @@
+Metadata-Version: 2.4
+Name: wayforth-mcp
+Version: 0.1.0
+Summary: MCP server for Wayforth — search engine and payment rail for AI agents
+Project-URL: Homepage, https://wayforth.io
+Project-URL: Repository, https://github.com/WayforthOfficial/wayforth
+Project-URL: Documentation, https://api-production-fd71.up.railway.app/docs
+License: MIT
+Keywords: agents,ai,api,mcp,wayforth
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: anthropic>=0.40
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0
+Description-Content-Type: text/markdown
+
+# wayforth-mcp
+
+MCP server for [Wayforth](https://github.com/your-org/wayforth) — discover AI services from Claude Code, Cursor, or any MCP-compatible client.
+
+## Install (one command)
+
+```bash
+claude mcp add wayforth -- uv run --directory ~/Code/wayforth/packages/mcp-server python server.py
+```
+
+That's it. Claude Code will restart and the three Wayforth tools will be available immediately.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `wayforth_search` | Search services by natural language intent, with optional category and tier filters |
+| `wayforth_list` | List all services, optionally filtered by category |
+| `wayforth_status` | Catalog stats (counts by tier and category) and API health |
+
+## Prerequisites
+
+The Wayforth API must be running:
+
+```bash
+cd ~/Code/wayforth/apps/api
+uv run uvicorn main:app --port 8000
+```
+
+By default the MCP server connects to `http://localhost:8000`. Override with:
+
+```bash
+export WAYFORTH_API_URL=https://api.wayforth.io
+```
+
+## Run manually (for testing)
+
+```bash
+cd ~/Code/wayforth/packages/mcp-server
+uv run python server.py
+```
+
+The server starts on stdio and waits for MCP protocol messages. Press `Ctrl+C` to exit.
+
+## Development
+
+```bash
+cd packages/mcp-server
+uv sync          # install deps
+uv run python server.py
+```

wayforth_mcp-0.1.0/README.md

@@ -0,0 +1,51 @@
+# wayforth-mcp
+
+MCP server for [Wayforth](https://github.com/your-org/wayforth) — discover AI services from Claude Code, Cursor, or any MCP-compatible client.
+
+## Install (one command)
+
+```bash
+claude mcp add wayforth -- uv run --directory ~/Code/wayforth/packages/mcp-server python server.py
+```
+
+That's it. Claude Code will restart and the three Wayforth tools will be available immediately.
+
+## Tools
+
+| Tool | Description |
+|---|---|
+| `wayforth_search` | Search services by natural language intent, with optional category and tier filters |
+| `wayforth_list` | List all services, optionally filtered by category |
+| `wayforth_status` | Catalog stats (counts by tier and category) and API health |
+
+## Prerequisites
+
+The Wayforth API must be running:
+
+```bash
+cd ~/Code/wayforth/apps/api
+uv run uvicorn main:app --port 8000
+```
+
+By default the MCP server connects to `http://localhost:8000`. Override with:
+
+```bash
+export WAYFORTH_API_URL=https://api.wayforth.io
+```
+
+## Run manually (for testing)
+
+```bash
+cd ~/Code/wayforth/packages/mcp-server
+uv run python server.py
+```
+
+The server starts on stdio and waits for MCP protocol messages. Press `Ctrl+C` to exit.
+
+## Development
+
+```bash
+cd packages/mcp-server
+uv sync          # install deps
+uv run python server.py
+```

wayforth_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[project]
+name = "wayforth-mcp"
+version = "0.1.0"
+description = "MCP server for Wayforth — search engine and payment rail for AI agents"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+dependencies = [
+    "mcp>=1.0.0",
+    "httpx>=0.27",
+    "python-dotenv>=1.0",
+    "anthropic>=0.40",
+]
+keywords = ["ai", "agents", "mcp", "wayforth", "api"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+]
+
+[project.scripts]
+wayforth-mcp = "server:main"
+
+[project.urls]
+Homepage = "https://wayforth.io"
+Repository = "https://github.com/WayforthOfficial/wayforth"
+Documentation = "https://api-production-fd71.up.railway.app/docs"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+include = ["server.py", "ranker.py"]
+
+[tool.mcp]
+name = "io.github.WayforthOfficial/wayforth"

wayforth_mcp-0.1.0/ranker.py

@@ -0,0 +1,79 @@
+import json
+import os
+from anthropic import AsyncAnthropic
+
+_client: AsyncAnthropic | None = None
+
+_SYSTEM = (
+    "You are a service ranker for AI agents. Given an agent's intent and a list of "
+    "services, return a JSON array of the same services ranked by relevance, each with "
+    "an added 'score' (0-100) and 'reason' (one sentence). "
+    "Return ONLY a JSON array, no explanation, no markdown, no code fences."
+)
+
+
+def _get_client() -> AsyncAnthropic | None:
+    key = os.getenv("ANTHROPIC_API_KEY")
+    if not key:
+        return None
+    global _client
+    if _client is None:
+        _client = AsyncAnthropic(api_key=key)
+    return _client
+
+
+def _keyword_rank(intent: str, services: list[dict]) -> list[dict]:
+    tokens = [w.lower() for w in intent.split() if len(w) > 2]
+
+    def _score(s: dict) -> int:
+        haystack = f"{s.get('name', '')} {s.get('description', '')}".lower()
+        return sum(1 for t in tokens if t in haystack)
+
+    ranked = sorted(services, key=_score, reverse=True)
+    for s in ranked:
+        s["score"] = _score(s) * 10
+        s["reason"] = "keyword match"
+    return ranked
+
+
+_HAIKU_CANDIDATE_LIMIT = 20  # pre-filter before sending to Haiku
+
+
+async def rank_services(intent: str, services: list[dict]) -> list[dict]:
+    """Rank services by semantic relevance using Claude Haiku; falls back to keyword ranking."""
+    client = _get_client()
+    if not client or not services:
+        return _keyword_rank(intent, list(services))
+
+    # Pre-filter: keyword rank → top N candidates so Haiku output fits in token budget
+    candidates = _keyword_rank(intent, [dict(s) for s in services])[:_HAIKU_CANDIDATE_LIMIT]
+
+    try:
+        slim = [
+            {"name": s.get("name"), "description": s.get("description"), "category": s.get("category")}
+            for s in candidates
+        ]
+        msg = await client.messages.create(
+            model="claude-haiku-4-5",
+            max_tokens=2048,
+            system=_SYSTEM,
+            messages=[{"role": "user", "content": f"Intent: {intent}\n\nServices:\n{json.dumps(slim)}"}],
+        )
+        text = msg.content[0].text
+        print(f"[DEBUG ranker] Haiku raw: {text[:500]!r}")
+        text = text.strip().removeprefix("```json").removeprefix("```").removesuffix("```").strip()
+        ranked_slim = json.loads(text)
+        name_to_meta = {item["name"]: item for item in ranked_slim}
+
+        result = []
+        for s in candidates:
+            s_copy = dict(s)
+            meta = name_to_meta.get(s.get("name"), {})
+            s_copy["score"] = int(meta.get("score", 0))
+            s_copy["reason"] = meta.get("reason", "")
+            result.append(s_copy)
+
+        return sorted(result, key=lambda x: x["score"], reverse=True)
+    except Exception as exc:
+        print(f"[DEBUG ranker] Haiku ranking failed ({exc!r}), falling back to keyword ranking")
+        return _keyword_rank(intent, candidates)

wayforth_mcp-0.1.0/server.json

@@ -0,0 +1,20 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.WayforthOfficial/wayforth",
+  "description": "Search engine and payment rail for AI agents. Discover 2,300+ agent-payable services across inference, data, and translation categories. Semantic ranking powered by Claude Haiku.",
+  "repository": {
+    "url": "https://github.com/WayforthOfficial/wayforth",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "wayforth-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

wayforth_mcp-0.1.0/server.py

@@ -0,0 +1,160 @@
+import os
+import httpx
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+from ranker import rank_services
+
+load_dotenv()
+
+API_BASE = os.getenv("WAYFORTH_API_URL", "https://api-production-fd71.up.railway.app")
+
+mcp = FastMCP("wayforth")
+
+TIER_LABELS = {0: "free", 1: "basic", 2: "standard", 3: "premium"}
+
+
+async def _fetch_services() -> list[dict] | None:
+    try:
+        async with httpx.AsyncClient(timeout=5.0) as client:
+            r = await client.get(f"{API_BASE}/services")
+            r.raise_for_status()
+            return r.json()
+    except Exception:
+        return None
+
+
+def _score(service: dict, tokens: list[str]) -> int:
+    haystack = f"{service.get('name', '')} {service.get('description', '')}".lower()
+    return sum(1 for t in tokens if t in haystack)
+
+
+def _format_ranked_service(idx: int, s: dict) -> str:
+    tier = TIER_LABELS.get(s.get("coverage_tier", 0), str(s.get("coverage_tier")))
+    price = s.get("pricing_usdc")
+    price_str = f"${float(price):.4f}" if price is not None else "$0"
+    score = s.get("score", 0)
+    reason = s.get("reason", "")
+    return (
+        f"{idx}. {s['name']} (score: {score}) — Reason: {reason}\n"
+        f"   Tier: {tier} | Price: {price_str} | Endpoint: {s.get('endpoint_url', 'N/A')}"
+    )
+
+
+def _format_service(s: dict) -> str:
+    tier = TIER_LABELS.get(s.get("coverage_tier", 0), str(s.get("coverage_tier")))
+    price = s.get("pricing_usdc")
+    price_str = f"${float(price):.4f} USDC" if price is not None else "free"
+    return (
+        f"**{s['name']}** [{s.get('category', 'unknown')} / tier {tier}]\n"
+        f"  {s.get('description') or 'No description'}\n"
+        f"  Pricing: {price_str} | Endpoint: {s.get('endpoint_url', 'N/A')}"
+    )
+
+
+@mcp.tool()
+async def wayforth_search(intent: str, category: str = None, max_tier: int = 2) -> str:
+    """Search Wayforth for AI services matching a natural language intent.
+
+    Args:
+        intent: What you're looking for, e.g. "translate Spanish documents"
+        category: Optional filter — inference, data, or translation
+        max_tier: Maximum coverage tier to include (0=free, 1=basic, 2=standard, 3=premium)
+    """
+    services = await _fetch_services()
+    if services is None:
+        return (
+            "Wayforth API is not reachable at "
+            f"{API_BASE}. Start the API with:\n"
+            "  cd apps/api && uv run uvicorn main:app --port 8000"
+        )
+
+    candidates = [
+        s for s in services
+        if (category is None or s.get("category") == category)
+        and s.get("coverage_tier", 0) <= max_tier
+    ]
+
+    ranked = await rank_services(intent, candidates)
+    top = ranked[:3]
+
+    if not top:
+        return f"No services found matching '{intent}'" + (
+            f" in category '{category}'" if category else ""
+        )
+
+    lines = [f"Top {len(top)} result(s) for \"{intent}\":\n"]
+    lines += [_format_ranked_service(i + 1, s) for i, s in enumerate(top)]
+    return "\n\n".join(lines)
+
+
+@mcp.tool()
+async def wayforth_list(category: str = None) -> str:
+    """List all services in the Wayforth catalog.
+
+    Args:
+        category: Optional filter — inference, data, or translation
+    """
+    services = await _fetch_services()
+    if services is None:
+        return (
+            "Wayforth API is not reachable at "
+            f"{API_BASE}. Start the API with:\n"
+            "  cd apps/api && uv run uvicorn main:app --port 8000"
+        )
+
+    filtered = [
+        s for s in services
+        if category is None or s.get("category") == category
+    ]
+
+    if not filtered:
+        return f"No services found" + (f" in category '{category}'" if category else "")
+
+    header = "All Wayforth services" + (f" — category: {category}" if category else "")
+    lines = [f"{header} ({len(filtered)} total):\n"]
+    lines += [_format_service(s) for s in filtered]
+    return "\n\n".join(lines)
+
+
+@mcp.tool()
+async def wayforth_status() -> str:
+    """Return catalog stats: service counts by tier and category, plus API health."""
+    services = await _fetch_services()
+    if services is None:
+        return (
+            f"API health: UNREACHABLE ({API_BASE})\n"
+            "Start with: cd apps/api && uv run uvicorn main:app --port 8000"
+        )
+
+    total = len(services)
+    by_category: dict[str, int] = {}
+    by_tier: dict[int, int] = {}
+
+    for s in services:
+        cat = s.get("category") or "unknown"
+        by_category[cat] = by_category.get(cat, 0) + 1
+        tier = s.get("coverage_tier", 0)
+        by_tier[tier] = by_tier.get(tier, 0) + 1
+
+    cat_lines = "\n".join(
+        f"  {cat}: {count}" for cat, count in sorted(by_category.items())
+    )
+    tier_lines = "\n".join(
+        f"  tier {t} ({TIER_LABELS.get(t, '?')}): {count}"
+        for t, count in sorted(by_tier.items())
+    )
+
+    return (
+        f"API health: OK ({API_BASE})\n"
+        f"Total services: {total}\n\n"
+        f"By category:\n{cat_lines}\n\n"
+        f"By tier:\n{tier_lines}"
+    )
+
+
+def main():
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()