hvtracker-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 YugantM
+
+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,102 @@
+# HVTracker MCP
+
+MCP server for checking supply-chain trust before connecting to AI agents,
+frameworks, or MCP servers.
+
+The hosted remote server is:
+
+```json
+{
+  "mcpServers": {
+    "hvtracker": {
+      "url": "https://hvtracker.net/mcp"
+    }
+  }
+}
+```
+
+This repository also provides a local stdio package for clients that prefer
+package-based installation.
+
+<!-- mcp-name: io.github.yugantm/hvtracker-mcp -->
+
+## Tools
+
+- `verify_mcp_server`: pre-connect trust verdict for an MCP server, package, GitHub repo, or agent name.
+- `check_agent_trust`: compact trust profile for a tracked AI agent or framework.
+- `search_agents`: search the HVTracker registry by name, repo, description, or category.
+
+## Local Install
+
+With npm:
+
+```bash
+npm install -g hvtracker-mcp
+```
+
+With PyPI:
+
+```bash
+python3 -m pip install hvtracker-mcp
+```
+
+Example MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "hvtracker": {
+      "command": "hvtracker-mcp"
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+python3 -m pip install -e ".[dev]"
+python3 -m pytest
+hvtracker-mcp
+```
+
+Use a different HVTracker base URL while testing:
+
+```bash
+HVTRACKER_BASE_URL=http://localhost:8080 hvtracker-mcp
+```
+
+## Registry Publishing
+
+The official MCP Registry manifest is `server.json`.
+
+```bash
+mcp-publisher login github
+mcp-publisher publish
+```
+
+In GitHub Actions, run the "Publish MCP Registry" workflow after the npm,
+PyPI, and GHCR packages for the same version are live.
+
+The server name is:
+
+```text
+io.github.yugantm/hvtracker-mcp
+```
+
+## Claude Desktop Extension
+
+Tagged releases build an `.mcpb` bundle for Claude Desktop from `manifest.json`.
+To build it locally:
+
+```bash
+npm ci --omit=dev
+npx @anthropic-ai/mcpb@2.1.2 pack
+```
+
+## Privacy
+
+HVTracker MCP sends the user-supplied search string or server identifier to
+`https://hvtracker.net` to fetch public trust data. It does not require an API
+key and does not write to user systems. See the HVTracker site for current data
+and methodology, and see `PRIVACY.md` for the repository privacy note.

package/bin/hvtracker-mcp.js

@@ -0,0 +1,210 @@
+#!/usr/bin/env node
+
+import { pathToFileURL } from "node:url";
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const VERSION = "0.1.0";
+const DEFAULT_BASE_URL = "https://hvtracker.net";
+const BASE_URL = (process.env.HVTRACKER_BASE_URL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+const TIMEOUT_MS = Number(process.env.HVTRACKER_TIMEOUT_SECONDS || 20) * 1000;
+const READ_ONLY = {
+  readOnlyHint: true,
+  destructiveHint: false,
+  idempotentHint: true,
+  openWorldHint: true
+};
+
+export async function apiGet(path, params = {}) {
+  const url = new URL(path, BASE_URL);
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && String(value) !== "") {
+      url.searchParams.set(key, String(value));
+    }
+  }
+
+  const response = await fetch(url, {
+    headers: { "user-agent": `hvtracker-mcp/${VERSION}` },
+    signal: AbortSignal.timeout(TIMEOUT_MS)
+  });
+  if (!response.ok) {
+    throw new Error(`HVTracker API returned ${response.status} for ${url.toString()}`);
+  }
+  const payload = await response.json();
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    throw new Error(`Unexpected response shape from ${url.toString()}`);
+  }
+  return payload;
+}
+
+function asToolResult(value) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    structuredContent: value
+  };
+}
+
+function agentProfile(agent) {
+  const slug = agent.slug;
+  return {
+    tracked: true,
+    name: agent.name,
+    repo: agent.repo,
+    trust_score: agent.trust_score,
+    evidence_grade: agent.evidence_grade,
+    rank: agent.rank,
+    category: agent.category,
+    has_provenance: agent.has_provenance,
+    scorecard_score: agent.scorecard_score,
+    mcp_server_support: agent.mcp_server_support?.status,
+    profile_url: slug ? `${BASE_URL}/agents/${slug}/` : null
+  };
+}
+
+export async function verifyMcpServer(server) {
+  try {
+    return await apiGet("/api/v1/mcp/verify", { server });
+  } catch (error) {
+    return {
+      server,
+      tracked: false,
+      trusted: false,
+      error: error instanceof Error ? error.message : String(error),
+      reasons: ["HVTracker could not fetch a verdict right now."]
+    };
+  }
+}
+
+export async function checkAgentTrust(nameOrRepo) {
+  const verdict = await verifyMcpServer(nameOrRepo);
+  if (!verdict.tracked) {
+    return {
+      query: nameOrRepo,
+      tracked: false,
+      trusted: false,
+      message: "Not in the HVTracker registry; treat as unverified.",
+      submit_url: `${BASE_URL}/submit`,
+      verdict
+    };
+  }
+
+  const slug = verdict.slug;
+  return {
+    query: nameOrRepo,
+    tracked: true,
+    trusted: verdict.trusted,
+    repo: verdict.resolved,
+    slug,
+    trust_score: verdict.trust_score,
+    evidence_grade: verdict.grade,
+    confidence: verdict.confidence,
+    mcp_server_support: verdict.mcp_server_support,
+    tool_permissions: verdict.tool_permissions || [],
+    profile_url: slug ? `${BASE_URL}/agents/${slug}/` : null,
+    reasons: verdict.reasons || []
+  };
+}
+
+export async function searchAgents(query = "", category = "", limit = 10) {
+  try {
+    const data = await apiGet("/api/v1/agents");
+    const ql = String(query || "").trim().toLowerCase();
+    const cl = String(category || "").trim().toLowerCase();
+    const matches = [];
+
+    for (const agent of data.agents || []) {
+      const haystack = ["name", "repo", "description", "slug"]
+        .map((key) => String(agent[key] || ""))
+        .join(" ")
+        .toLowerCase();
+      if (ql && !haystack.includes(ql)) {
+        continue;
+      }
+      if (cl && String(agent.category || "").toLowerCase() !== cl) {
+        continue;
+      }
+      matches.push(agentProfile(agent));
+    }
+
+    matches.sort((a, b) => {
+      if (a.trust_score == null && b.trust_score != null) return 1;
+      if (a.trust_score != null && b.trust_score == null) return -1;
+      return (b.trust_score || 0) - (a.trust_score || 0);
+    });
+
+    const safeLimit = Math.max(1, Math.min(Number.parseInt(limit, 10) || 10, 50));
+    return { count: matches.length, results: matches.slice(0, safeLimit) };
+  } catch (error) {
+    return {
+      count: 0,
+      results: [],
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+export function createServer() {
+  const server = new McpServer({
+    name: "hvtracker",
+    version: VERSION,
+    instructions: "Check trust signals for AI agents and MCP servers."
+  });
+
+  server.registerTool(
+    "verify_mcp_server",
+    {
+      title: "Verify MCP Server",
+      description: "Pre-connect trust verdict for an MCP server or AI agent.",
+      inputSchema: {
+        server: z.string().describe("GitHub repo, package, display name, slug, or MCP URL.")
+      },
+      annotations: READ_ONLY
+    },
+    async ({ server }) => asToolResult(await verifyMcpServer(server))
+  );
+
+  server.registerTool(
+    "check_agent_trust",
+    {
+      title: "Check Agent Trust",
+      description: "Get the HVTracker trust profile for a tracked AI agent or framework.",
+      inputSchema: {
+        name_or_repo: z.string().describe("Agent name, slug, GitHub repo, package, or MCP URL.")
+      },
+      annotations: READ_ONLY
+    },
+    async ({ name_or_repo }) => asToolResult(await checkAgentTrust(name_or_repo))
+  );
+
+  server.registerTool(
+    "search_agents",
+    {
+      title: "Search Agents",
+      description: "Search tracked AI agents and frameworks by name, repo, or description.",
+      inputSchema: {
+        query: z.string().optional().default(""),
+        category: z.string().optional().default(""),
+        limit: z.number().int().min(1).max(50).optional().default(10)
+      },
+      annotations: READ_ONLY
+    },
+    async ({ query = "", category = "", limit = 10 }) =>
+      asToolResult(await searchAgents(query, category, limit))
+  );
+
+  return server;
+}
+
+export async function runStdio() {
+  const server = createServer();
+  await server.connect(new StdioServerTransport());
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  runStdio().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "hvtracker-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for HVTracker trust checks.",
+  "license": "MIT",
+  "type": "module",
+  "mcpName": "io.github.yugantm/hvtracker-mcp",
+  "bin": {
+    "hvtracker-mcp": "./bin/hvtracker-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "README.md",
+    "LICENSE",
+    "server.json"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-agents",
+    "trust",
+    "supply-chain"
+  ],
+  "author": "YugantM",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YugantM/hvtracker-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YugantM/hvtracker-mcp/issues"
+  },
+  "homepage": "https://hvtracker.net",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.0"
+  }
+}

package/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.yugantm/hvtracker-mcp",
+  "title": "HVTracker MCP",
+  "description": "Pre-connect trust checks for AI agents and MCP servers using HVTracker's public trust registry.",
+  "version": "0.1.0",
+  "repository": {
+    "url": "https://github.com/YugantM/hvtracker-mcp",
+    "source": "github"
+  },
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://hvtracker.net/mcp"
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "hvtracker-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "pypi",
+      "identifier": "hvtracker-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    },
+    {
+      "registryType": "oci",
+      "identifier": "ghcr.io/yugantm/hvtracker-mcp:0.1.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ],
+  "tags": ["security", "trust", "ai-agents", "mcp", "supply-chain"]
+}