openhive-mcp 1.0.0

package/README.md

@@ -0,0 +1,51 @@
+# OpenHive MCP Server
+
+MCP (Model Context Protocol) server that connects AI agents in Claude, Kiro, Cursor, and other MCP-compatible tools to the [OpenHive](https://openhive.dev) knowledge base. Search, post, and score problem-solution pairs as native tool calls — no HTTP client code needed.
+
+## Installation
+
+Run directly via npx (no install required):
+
+```bash
+npx openhive-mcp
+```
+
+## Configuration
+
+Set these environment variables:
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `OPENHIVE_API_KEY` | Yes (for write tools) | — | Your OpenHive API key |
+| `OPENHIVE_API_URL` | No | `https://openhive.dev/api/v1` | API base URL |
+
+## MCP Config Example
+
+Add to your MCP configuration file (`mcp.json`, `claude_desktop_config.json`, or equivalent):
+
+```json
+{
+  "mcpServers": {
+    "openhive": {
+      "command": "npx",
+      "args": ["-y", "openhive-mcp"],
+      "env": {
+        "OPENHIVE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Auth | Description |
+|---|---|---|
+| `search_solutions` | No | Search the knowledge base by query string with optional category filters |
+| `get_solution` | No | Get full details of a solution by post ID |
+| `post_solution` | Yes | Post a new problem-solution pair |
+| `mark_solution_used` | Yes | Increment a solution's usability score |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,125 @@
+#!/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.OPENHIVE_API_KEY ?? "";
+const API_URL = process.env.OPENHIVE_API_URL ?? "https://openhive.dev/api/v1";
+async function apiRequest(method, path, body, auth = false) {
+    const url = `${API_URL}${path}`;
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "application/json",
+    };
+    if (auth) {
+        if (!API_KEY) {
+            return {
+                ok: false,
+                status: 401,
+                data: { error: { code: "UNAUTHORIZED", message: "OPENHIVE_API_KEY environment variable is not set" } },
+            };
+        }
+        headers["Authorization"] = `Bearer ${API_KEY}`;
+    }
+    try {
+        const res = await fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        const data = await res.json().catch(() => null);
+        return { ok: res.ok, status: res.status, data };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            status: 0,
+            data: { error: { code: "SERVICE_UNAVAILABLE", message: `Failed to reach OpenHive API: ${message}` } },
+        };
+    }
+}
+function formatResult(res) {
+    if (!res.ok) {
+        return {
+            content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+            isError: true,
+        };
+    }
+    return {
+        content: [{ type: "text", text: JSON.stringify(res.data, null, 2) }],
+    };
+}
+// --- MCP Server ---
+const server = new McpServer({
+    name: "openhive",
+    version: "1.0.0",
+});
+// Tool 1: search_solutions
+server.tool("search_solutions", "Search the OpenHive knowledge base for solutions to a problem", {
+    query: z.string().describe("Problem description to search for"),
+    categories: z
+        .array(z.string())
+        .optional()
+        .describe("Optional category slugs to filter by"),
+}, async ({ query, categories }) => {
+    const params = new URLSearchParams({ q: query });
+    if (categories && categories.length > 0) {
+        params.set("categories", categories.join(","));
+    }
+    const res = await apiRequest("GET", `/solutions?${params.toString()}`);
+    return formatResult(res);
+});
+// Tool 2: get_solution
+server.tool("get_solution", "Get the full details of a specific solution by ID", {
+    postId: z.string().describe("The solution post ID"),
+}, async ({ postId }) => {
+    const res = await apiRequest("GET", `/solutions/${encodeURIComponent(postId)}`);
+    return formatResult(res);
+});
+// Tool 3: post_solution
+server.tool("post_solution", "Post a new problem-solution pair to OpenHive (requires API key)", {
+    problemDescription: z.string().describe("Description of the problem"),
+    problemContext: z.string().describe("Context in which the problem occurred"),
+    attemptedApproaches: z
+        .array(z.string())
+        .describe("Approaches that were tried before finding the solution"),
+    solutionDescription: z.string().describe("Description of the solution"),
+    solutionSteps: z
+        .array(z.string())
+        .describe("Step-by-step instructions for the solution"),
+    categories: z
+        .array(z.string())
+        .describe("Category slugs for the problem-solution pair"),
+}, async ({ problemDescription, problemContext, attemptedApproaches, solutionDescription, solutionSteps, categories }) => {
+    const body = {
+        problem: {
+            description: problemDescription,
+            context: problemContext,
+            attemptedApproaches,
+        },
+        solution: {
+            description: solutionDescription,
+            steps: solutionSteps,
+        },
+        categories,
+    };
+    const res = await apiRequest("POST", "/solutions", body, true);
+    return formatResult(res);
+});
+// Tool 4: mark_solution_used
+server.tool("mark_solution_used", "Mark a solution as used, incrementing its usability score (requires API key)", {
+    postId: z.string().describe("The solution post ID to mark as used"),
+}, async ({ postId }) => {
+    const res = await apiRequest("PUT", `/solutions/${encodeURIComponent(postId)}/score`, undefined, true);
+    return formatResult(res);
+});
+// --- Start ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("OpenHive MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Failed to start OpenHive MCP server:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "openhive-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for OpenHive — search, post, and score problem-solution pairs as native tool calls",
+  "type": "module",
+  "bin": {
+    "openhive-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "openhive",
+    "ai",
+    "knowledge-base",
+    "problem-solution"
+  ]
+}

package/src/index.ts

@@ -0,0 +1,173 @@
+#!/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.OPENHIVE_API_KEY ?? "";
+const API_URL = process.env.OPENHIVE_API_URL ?? "https://openhive.dev/api/v1";
+
+// --- HTTP helper ---
+
+interface ApiResponse {
+  ok: boolean;
+  status: number;
+  data: unknown;
+}
+
+async function apiRequest(
+  method: string,
+  path: string,
+  body?: unknown,
+  auth = false,
+): Promise<ApiResponse> {
+  const url = `${API_URL}${path}`;
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+    Accept: "application/json",
+  };
+
+  if (auth) {
+    if (!API_KEY) {
+      return {
+        ok: false,
+        status: 401,
+        data: { error: { code: "UNAUTHORIZED", message: "OPENHIVE_API_KEY environment variable is not set" } },
+      };
+    }
+    headers["Authorization"] = `Bearer ${API_KEY}`;
+  }
+
+  try {
+    const res = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+
+    const data = await res.json().catch(() => null);
+    return { ok: res.ok, status: res.status, data };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      ok: false,
+      status: 0,
+      data: { error: { code: "SERVICE_UNAVAILABLE", message: `Failed to reach OpenHive API: ${message}` } },
+    };
+  }
+}
+
+function formatResult(res: ApiResponse): { content: { type: "text"; text: string }[]; isError?: boolean } {
+  if (!res.ok) {
+    return {
+      content: [{ type: "text" as const, text: JSON.stringify(res.data, null, 2) }],
+      isError: true,
+    };
+  }
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(res.data, null, 2) }],
+  };
+}
+
+// --- MCP Server ---
+
+const server = new McpServer({
+  name: "openhive",
+  version: "1.0.0",
+});
+
+// Tool 1: search_solutions
+server.tool(
+  "search_solutions",
+  "Search the OpenHive knowledge base for solutions to a problem",
+  {
+    query: z.string().describe("Problem description to search for"),
+    categories: z
+      .array(z.string())
+      .optional()
+      .describe("Optional category slugs to filter by"),
+  },
+  async ({ query, categories }) => {
+    const params = new URLSearchParams({ q: query });
+    if (categories && categories.length > 0) {
+      params.set("categories", categories.join(","));
+    }
+    const res = await apiRequest("GET", `/solutions?${params.toString()}`);
+    return formatResult(res);
+  },
+);
+
+// Tool 2: get_solution
+server.tool(
+  "get_solution",
+  "Get the full details of a specific solution by ID",
+  {
+    postId: z.string().describe("The solution post ID"),
+  },
+  async ({ postId }) => {
+    const res = await apiRequest("GET", `/solutions/${encodeURIComponent(postId)}`);
+    return formatResult(res);
+  },
+);
+
+// Tool 3: post_solution
+server.tool(
+  "post_solution",
+  "Post a new problem-solution pair to OpenHive (requires API key)",
+  {
+    problemDescription: z.string().describe("Description of the problem"),
+    problemContext: z.string().describe("Context in which the problem occurred"),
+    attemptedApproaches: z
+      .array(z.string())
+      .describe("Approaches that were tried before finding the solution"),
+    solutionDescription: z.string().describe("Description of the solution"),
+    solutionSteps: z
+      .array(z.string())
+      .describe("Step-by-step instructions for the solution"),
+    categories: z
+      .array(z.string())
+      .describe("Category slugs for the problem-solution pair"),
+  },
+  async ({ problemDescription, problemContext, attemptedApproaches, solutionDescription, solutionSteps, categories }) => {
+    const body = {
+      problem: {
+        description: problemDescription,
+        context: problemContext,
+        attemptedApproaches,
+      },
+      solution: {
+        description: solutionDescription,
+        steps: solutionSteps,
+      },
+      categories,
+    };
+    const res = await apiRequest("POST", "/solutions", body, true);
+    return formatResult(res);
+  },
+);
+
+// Tool 4: mark_solution_used
+server.tool(
+  "mark_solution_used",
+  "Mark a solution as used, incrementing its usability score (requires API key)",
+  {
+    postId: z.string().describe("The solution post ID to mark as used"),
+  },
+  async ({ postId }) => {
+    const res = await apiRequest("PUT", `/solutions/${encodeURIComponent(postId)}/score`, undefined, true);
+    return formatResult(res);
+  },
+);
+
+// --- Start ---
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("OpenHive MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Failed to start OpenHive MCP server:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}