hugging-bay-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugging Bay
+
+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.

package/README.md

@@ -0,0 +1,120 @@
+# hugging-bay-mcp
+
+Model Context Protocol (MCP) server for [Hugging Bay](https://huggingbay.xyz) — the
+agent-friendly open AI catalog. It exposes Hugging Bay's public catalog search, hosted
+downloads, trust/provenance signals, mirror demand, curated stacks, citation-ready answer
+packs, and agent-discovery contracts as MCP tools that any MCP client (Claude Desktop,
+Cursor, and others) can call.
+
+The server is a thin **stdio** launcher that proxies to the live Hugging Bay API. Public
+read-only tools work with no credentials; authenticated watchlist and publisher tools
+activate when you supply a Hugging Bay bearer token.
+
+- Live remote MCP endpoint (streamable-http): `https://huggingbay.xyz/api/mcp`
+- Canonical tool catalog / discovery doc: <https://huggingbay.xyz/.well-known/mcp.json>
+
+## Install / run
+
+No install needed — run it on demand with npx:
+
+```bash
+npx hugging-bay-mcp
+```
+
+Or install globally:
+
+```bash
+npm install -g hugging-bay-mcp
+hugging-bay-mcp
+```
+
+## Environment variables
+
+| Variable | Required | Default | Purpose |
+| --- | --- | --- | --- |
+| `HUGGING_BAY_API` | no | `https://huggingbay.xyz` | Hugging Bay API base URL. |
+| `HUGGING_BAY_TOKEN` | no | — | Bearer token (`hb_...`). Enables authenticated watchlist and publisher/admin tools. Public tools work without it. |
+
+`HUGGING_BAY_ADMIN_TOKEN`, `HUGGING_BAY_PUBLISHER_TOKEN`, and `HUGGING_BAY_READER_TOKEN`
+are also honored as fallbacks for `HUGGING_BAY_TOKEN`.
+
+## Claude Desktop
+
+Add to `claude_desktop_config.json`
+(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "hugging-bay": {
+      "command": "npx",
+      "args": ["-y", "hugging-bay-mcp"],
+      "env": {
+        "HUGGING_BAY_API": "https://huggingbay.xyz"
+      }
+    }
+  }
+}
+```
+
+To enable authenticated tools, add your token to `env`:
+
+```json
+"env": {
+  "HUGGING_BAY_API": "https://huggingbay.xyz",
+  "HUGGING_BAY_TOKEN": "hb_your_token_here"
+}
+```
+
+## Cursor
+
+Add to `~/.cursor/mcp.json` (or a project `.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "hugging-bay": {
+      "command": "npx",
+      "args": ["-y", "hugging-bay-mcp"],
+      "env": {
+        "HUGGING_BAY_API": "https://huggingbay.xyz"
+      }
+    }
+  }
+}
+```
+
+## Tool catalog
+
+The server ships a large set of tools. The authoritative, always-current list (names,
+descriptions, and input schemas) is published at
+<https://huggingbay.xyz/.well-known/mcp.json>. Highlights:
+
+- **Discovery & search** — `search_artifacts`, `resolve_artifact`, `get_artifact`,
+  `get_artifact_bundle`, `compare_artifacts`, `list_topics`, `get_topic`.
+- **Downloads & local use** — `get_download_plan`, `get_local_kit`, `list_files`,
+  `list_downloadable_files`, `preview_file`.
+- **Trust & provenance** — `get_trust_bundle`, `get_release_readiness`,
+  `get_manifest_signing_key`, `get_artifact_reviews`, `get_community_signals`.
+- **Rankings, stacks & answer packs** — `get_ranking`, `list_stacks`, `get_stack`,
+  `list_answer_packs`, `get_answer_pack`, `get_citation_pack`.
+- **Mirror demand** — `list_mirror_demand`, `get_mirror_readiness`, `request_mirror`,
+  `request_source_indexing`.
+- **Agent discovery** — `get_agent_discovery`, `get_agent_tasks`, `get_ai_search_guidance`,
+  `get_health`, `get_catalog_coverage`, `get_trending`.
+
+## Safety notes
+
+- **Public tools are read-only** and require no credentials — they only read Hugging Bay's
+  public catalog and discovery surfaces.
+- **Authenticated tools** (saved searches/watchlists, publisher dashboard, upload sessions,
+  mirror/import administration) require a Hugging Bay bearer token via `HUGGING_BAY_TOKEN`.
+  Their scope is limited to what the token's role permits.
+- The server does **not** execute downloads or move data itself; download/mirror tools
+  return signed URLs, hashes, and copyable commands for you to run.
+- Your token is sent only as a bearer `Authorization` header to `HUGGING_BAY_API`. Keep it
+  secret; never commit it.
+
+## License
+
+MIT