githunt-mcp 0.1.0

package/README.md

@@ -0,0 +1,68 @@
+# githunt-mcp
+
+MCP server that wraps [GitHunt's](https://githunt.ai) REST API, giving AI assistants access to GitHunt's GitHub developer search, profile lookup, and AI profile analysis.
+
+## Setup
+
+Get an API key from your [GitHunt account](https://githunt.ai/account), then run:
+
+```bash
+npx githunt-mcp
+```
+
+### Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GITHUNT_API_KEY` | yes | Your GitHunt API key |
+| `GITHUNT_API_URL` | no | API base URL (default `https://api.githunt.ai`) |
+
+### Claude Code
+
+```bash
+claude mcp add githunt -e GITHUNT_API_KEY=your-key-here -- npx githunt-mcp
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "githunt": {
+      "command": "npx",
+      "args": ["githunt-mcp"],
+      "env": {
+        "GITHUNT_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "githunt": {
+      "command": "npx",
+      "args": ["githunt-mcp"],
+      "env": {
+        "GITHUNT_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+- **search_developers** — search GitHunt's index of 318k+ GitHub developers by location, role, and skills.
+- **get_developer** — get a single GitHub developer's ranked profile by username.
+- **analyze_profile** — deep AI analysis of a GitHub profile (proficiency, role matches, extracted emails).
+
+Full API reference: https://docs.githunt.ai

package/index.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const API_KEY = process.env.GITHUNT_API_KEY;
+if (!API_KEY) {
+  console.error(
+    "GITHUNT_API_KEY environment variable is required. Get a key at https://githunt.ai/account."
+  );
+  process.exit(1);
+}
+
+const API_URL = (process.env.GITHUNT_API_URL || "https://api.githunt.ai").replace(/\/+$/, "");
+
+async function callApi(path, options = {}) {
+  const res = await fetch(`${API_URL}${path}`, {
+    ...options,
+    headers: {
+      Authorization: `Bearer ${API_KEY}`,
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+  const body = await res.json().catch(() => null);
+  return { ok: res.ok, body };
+}
+
+function truncate(text, max) {
+  if (!text) return "";
+  const clean = String(text).replace(/\s+/g, " ").trim();
+  return clean.length > max ? `${clean.slice(0, max - 3)}...` : clean;
+}
+
+function joinPresent(parts, sep = " | ") {
+  return parts
+    .map((p) => (typeof p === "string" ? p.trim() : p))
+    .filter(Boolean)
+    .join(sep);
+}
+
+function relativeActive(dateString) {
+  if (!dateString) return "";
+  const diffDays = Math.floor((Date.now() - new Date(dateString).getTime()) / 86400000);
+  if (Number.isNaN(diffDays)) return "";
+  if (diffDays < 1) return "active today";
+  if (diffDays < 7) return `active ${diffDays}d ago`;
+  if (diffDays < 30) return `active ${Math.floor(diffDays / 7)}w ago`;
+  if (diffDays < 365) return `active ${Math.floor(diffDays / 30)}mo ago`;
+  return `active ${Math.floor(diffDays / 365)}y ago`;
+}
+
+function formatSearchResults(data) {
+  const header = `${data.matchedCount} candidate${data.matchedCount === 1 ? "" : "s"} found`;
+  if (!data.results?.length) {
+    return `${header}. Try a broader location or fewer skills.`;
+  }
+  const blocks = data.results.map((r, i) => {
+    const identity = joinPresent([
+      `${i + 1}. ${r.login}${r.name && r.name !== r.login ? ` (${r.name})` : ""} - score ${r.score}`,
+      `profile ${r.profile_score} / tech ${r.tech_stack_score} / activity ${r.activity_score}`,
+    ]);
+    const meta = joinPresent([
+      r.github_experience ? `${r.github_experience}y on GitHub` : "",
+      r.location,
+      r.company ? `@ ${truncate(r.company.replace(/^@/, ""), 40)}` : "",
+      typeof r.followers === "number" ? `${r.followers} followers` : "",
+      r.hireable === "Yes" ? "hireable" : "",
+      r.email,
+      r.profile_url,
+    ]);
+    const activity = joinPresent([
+      relativeActive(r.last_active_date),
+      r.commit_frequency_label && r.commit_frequency_label !== "Unknown"
+        ? `${r.commit_frequency_label} (${r.commits_per_month || 0} commits/mo)`
+        : "",
+      r.commit_message_quality_label && r.commit_message_quality_label !== "Insufficient Data"
+        ? `commit quality ${r.commit_message_quality_label} (${r.semantic_commit_percentage || 0}% semantic)`
+        : "",
+    ]);
+    const details = joinPresent([
+      r.matching_keywords ? `matched: ${truncate(r.matching_keywords, 90)}` : "",
+      r.bio ? `bio: ${truncate(r.bio, 90)}` : "",
+    ]);
+    const repos = (r.top_repositories || [])
+      .map((repo) => joinPresent([repo.name, repo.stars ? `${repo.stars}★` : "", repo.language], " "))
+      .join(", ");
+    const oss = (r.top_oss_contributions || [])
+      .map((c) => joinPresent([c.repository, c.tier_label ? `(${c.tier_label})` : ""], " "))
+      .join(", ");
+    return joinPresent(
+      [
+        identity,
+        `   ${meta}`,
+        activity ? `   ${activity}` : "",
+        details ? `   ${details}` : "",
+        repos ? `   repos: ${repos}` : "",
+        oss ? `   OSS: ${oss}` : "",
+      ],
+      "\n"
+    );
+  });
+  return `${header}\n\n${blocks.join("\n\n")}`;
+}
+
+function formatDeveloper(r) {
+  const repos = (r.top_repositories || [])
+    .map((repo) => joinPresent([repo.name, repo.stars ? `${repo.stars}★` : "", repo.language], " "))
+    .join(", ");
+  const oss = (r.top_oss_contributions || [])
+    .map((c) => joinPresent([c.repository, c.tier_label ? `(${c.tier_label})` : ""], " "))
+    .join(", ");
+  return [
+    `${r.username}${r.name && r.name !== r.username ? ` (${r.name})` : ""} - score ${r.score}`,
+    joinPresent([
+      `profile ${r.profile_score} / tech ${r.tech_stack_score} / activity ${r.activity_score}`,
+      r.github_experience ? `${r.github_experience}y on GitHub` : "",
+      `hireable: ${r.hireable}`,
+    ]),
+    joinPresent([r.location, r.company, `${r.followers} followers`]),
+    joinPresent([
+      relativeActive(r.last_active_date),
+      r.commit_frequency_label && r.commit_frequency_label !== "Unknown"
+        ? `${r.commit_frequency_label} (${r.commits_per_month || 0} commits/mo)`
+        : "",
+      r.commit_message_quality_label && r.commit_message_quality_label !== "Insufficient Data"
+        ? `commit quality ${r.commit_message_quality_label} (${r.semantic_commit_percentage || 0}% semantic)`
+        : "",
+    ]),
+    joinPresent([r.email, r.blog, r.twitter_username ? `@${r.twitter_username}` : ""]),
+    r.matching_keywords ? `keywords: ${truncate(r.matching_keywords, 120)}` : "",
+    r.bio ? `bio: ${truncate(r.bio, 160)}` : "",
+    repos ? `repos: ${repos}` : "",
+    oss ? `OSS: ${oss}` : "",
+    r.profile_url,
+  ].filter(Boolean).join("\n");
+}
+
+function formatAnalysis(data) {
+  const prof = data.proficiency || {};
+  const roles = (data.roleMatch || []).slice(0, 3);
+  const emails = data.emails?.emails || [];
+  return [
+    `Proficiency: ${prof.level || "unknown"} (score ${prof.score ?? "n/a"}, ~${prof.experienceYears ?? "?"}y experience)`,
+    roles.length
+      ? `Role fit: ${roles.map((r) => `${r.displayName || r.role} (${r.score})`).join(", ")}`
+      : "",
+    emails.length
+      ? `Emails: ${emails.map((e) => `${e.address}${e.isPrimary ? " (primary)" : ""}`).join(", ")}`
+      : "Emails: none found",
+    data.scores?.matchingKeywords?.length
+      ? `Keywords: ${truncate(data.scores.matchingKeywords.join(", "), 120)}`
+      : "",
+  ].filter(Boolean).join("\n");
+}
+
+function formatSuccess(data, meta, formatter) {
+  const lines = [formatter ? formatter(data) : JSON.stringify(data, null, 2)];
+  if (meta?.quota) {
+    lines.push(`Quota: ${meta.quota.used}/${meta.quota.limit} for ${meta.quota.month}`);
+  }
+  return { content: [{ type: "text", text: lines.join("\n\n") }] };
+}
+
+function formatError(body, networkErrorMessage) {
+  if (networkErrorMessage) {
+    return { isError: true, content: [{ type: "text", text: `Network error: ${networkErrorMessage}` }] };
+  }
+  const error = body?.error || {};
+  const code = error.code || "unknown_error";
+  const message = error.message || "Request failed.";
+  const text =
+    code === "quota_exceeded"
+      ? `Quota exceeded: your monthly or daily quota is exhausted. Upgrade at https://githunt.ai/pricing.`
+      : `${code}: ${message}`;
+  return { isError: true, content: [{ type: "text", text }] };
+}
+
+async function handleApiCall(path, options = {}, formatter = null) {
+  let result;
+  try {
+    result = await callApi(path, options);
+  } catch (err) {
+    return formatError(null, err.message);
+  }
+  if (!result.ok || !result.body?.success) {
+    return formatError(result.body);
+  }
+  return formatSuccess(result.body.data, result.body.meta, formatter);
+}
+
+const server = new McpServer({ name: "githunt", version: "0.1.0" });
+
+server.registerTool(
+  "search_developers",
+  {
+    description:
+      "Search GitHunt's index of 318k+ GitHub developers by location, role, and skills. Returns ranked candidates with scores and contact info.",
+    inputSchema: {
+      location: z.string(),
+      role: z.string().optional(),
+      skills: z.array(z.string()).max(20).optional(),
+      languages: z.array(z.string()).max(10).optional(),
+      minExperienceYears: z.number().min(0).max(50).optional(),
+      isHireable: z.boolean().optional(),
+      strictSkills: z.boolean().optional(),
+      maxResults: z.number().min(1).max(100).default(25).optional(),
+    },
+  },
+  async (args) =>
+    handleApiCall("/v1/search", {
+      method: "POST",
+      body: JSON.stringify(args),
+    }, formatSearchResults)
+);
+
+server.registerTool(
+  "get_developer",
+  {
+    description:
+      "Get a single GitHub developer's ranked profile by username (score, experience, contact info).",
+    inputSchema: {
+      login: z.string(),
+    },
+  },
+  async ({ login }) => handleApiCall(`/v1/users/${encodeURIComponent(login)}`, {}, formatDeveloper)
+);
+
+server.registerTool(
+  "analyze_profile",
+  {
+    description:
+      "Deep AI analysis of a GitHub profile: proficiency level, role matches, extracted emails. Slower and more expensive than get_developer.",
+    inputSchema: {
+      username: z.string(),
+    },
+  },
+  async (args) =>
+    handleApiCall("/v1/profile/analyze", {
+      method: "POST",
+      body: JSON.stringify(args),
+    }, formatAnalysis)
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "githunt-mcp",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "MCP server for GitHunt's GitHub talent search API",
+  "bin": {
+    "githunt-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mordka/githunt.git",
+    "directory": "mcp"
+  },
+  "homepage": "https://docs.githunt.ai",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "github",
+    "developer-search",
+    "recruiting",
+    "githunt"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}