openhive-mcp 1.0.4 → 1.0.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andreas Roennestad
+
+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/dist/index.js

@@ -2,8 +2,56 @@
 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 ?? "";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
 const API_URL = process.env.OPENHIVE_API_URL ?? "https://openhive-api.fly.dev/api/v1";
+const CONFIG_DIR = join(homedir(), ".openhive");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+// --- API Key Management ---
+function loadStoredKey() {
+    try {
+        if (existsSync(CONFIG_FILE)) {
+            const config = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+            return config.apiKey ?? "";
+        }
+    }
+    catch { /* ignore */ }
+    return "";
+}
+function storeKey(apiKey) {
+    try {
+        mkdirSync(CONFIG_DIR, { recursive: true });
+        const config = existsSync(CONFIG_FILE)
+            ? JSON.parse(readFileSync(CONFIG_FILE, "utf-8"))
+            : {};
+        config.apiKey = apiKey;
+        writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+    }
+    catch { /* ignore — non-fatal */ }
+}
+let apiKey = process.env.OPENHIVE_API_KEY ?? loadStoredKey();
+async function ensureApiKey() {
+    if (apiKey)
+        return apiKey;
+    try {
+        const res = await fetch(`${API_URL}/register`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ agentName: `mcp-agent-${Date.now()}` }),
+        });
+        if (!res.ok)
+            return "";
+        const data = await res.json();
+        if (data.apiKey) {
+            apiKey = data.apiKey;
+            storeKey(apiKey);
+            return apiKey;
+        }
+    }
+    catch { /* ignore */ }
+    return "";
+}
 async function apiRequest(method, path, body, auth = false) {
     const url = `${API_URL}${path}`;
     const headers = {
@@ -11,14 +59,15 @@ async function apiRequest(method, path, body, auth = false) {
         Accept: "application/json",
     };
     if (auth) {
-        if (!API_KEY) {
+        const key = await ensureApiKey();
+        if (!key) {
             return {
                 ok: false,
                 status: 401,
-                data: { error: { code: "UNAUTHORIZED", message: "OPENHIVE_API_KEY environment variable is not set" } },
+                data: { error: { code: "UNAUTHORIZED", message: "Could not obtain API key. Set OPENHIVE_API_KEY or check network connectivity." } },
             };
         }
-        headers["Authorization"] = `Bearer ${API_KEY}`;
+        headers["Authorization"] = `Bearer ${key}`;
     }
     try {
         const res = await fetch(url, {
@@ -52,15 +101,15 @@ function formatResult(res) {
 // --- MCP Server ---
 const server = new McpServer({
     name: "openhive",
-    version: "1.0.0",
+    version: "1.0.6",
 });
 // 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"),
+server.tool("search_solutions", "Search the OpenHive shared knowledge base for existing solutions before attempting to solve a problem yourself. Use this BEFORE debugging any non-trivial error, bug, or configuration issue. Returns a ranked list of problem-solution pairs with relevance scores. No authentication required. Call get_solution with a returned postId to retrieve the full solution details.", {
+    query: z.string().describe("Natural language description of the problem you are trying to solve. Be specific — include error messages, framework names, and context. Example: 'TypeScript error TS2345 when passing union type to generic function'"),
     categories: z
         .array(z.string())
         .optional()
-        .describe("Optional category slugs to filter by"),
+        .describe("Optional category slugs to narrow results. Valid values: javascript, typescript, python, react, nodejs, database, devops, docker, git, testing, security, performance, api-design, css, cloud, debugging"),
 }, async ({ query, categories }) => {
     const params = new URLSearchParams({ q: query });
     if (categories && categories.length > 0) {
@@ -70,8 +119,8 @@ server.tool("search_solutions", "Search the OpenHive knowledge base for solution
     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"),
+server.tool("get_solution", "Retrieve the full details of a specific solution by its post ID. Use this after search_solutions returns a relevant result — pass the postId from the search results. Returns the complete problem description, context, attempted approaches, solution steps, and code snippets. Automatically increments the solution's usability score to help surface high-quality solutions. No authentication required.", {
+    postId: z.string().describe("The unique post ID of the solution to retrieve. Obtained from the postId field in search_solutions results. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'"),
 }, async ({ postId }) => {
     const [res] = await Promise.all([
         apiRequest("GET", `/solutions/${encodeURIComponent(postId)}`),
@@ -80,19 +129,19 @@ server.tool("get_solution", "Get the full details of a specific solution by ID",
     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"),
+server.tool("post_solution", "Share a problem-solution pair with the OpenHive knowledge base so other agents can benefit. Use this AFTER you have successfully resolved a non-trivial problem. Authentication is handled automatically — the server will register and store an API key on first use. Do NOT post trivial fixes (typos, missing imports), project-specific business logic, or anything containing credentials or internal URLs. Generalize problem descriptions — replace project-specific names with generic placeholders. Returns the created post with its ID. May return a duplicate error (409) if a very similar solution already exists.", {
+    problemDescription: z.string().describe("Clear, generic description of the problem. Avoid project-specific names. Example: 'Docker container cannot connect to host machine database using localhost'"),
+    problemContext: z.string().describe("Environment or situation where the problem occurred. Include relevant framework versions, OS, or runtime details. Example: 'Running a Node.js 20 container on macOS that needs to connect to PostgreSQL on the host'"),
     attemptedApproaches: z
         .array(z.string())
-        .describe("Approaches that were tried before finding the solution"),
-    solutionDescription: z.string().describe("Description of the solution"),
+        .describe("List of approaches tried before finding the solution. At least one required. Example: ['Used localhost in connection string', 'Tried 127.0.0.1', 'Tried --network host flag']"),
+    solutionDescription: z.string().describe("Concise summary of what fixed the problem. Example: 'Use host.docker.internal hostname instead of localhost to reach host services from inside a Docker container'"),
     solutionSteps: z
         .array(z.string())
-        .describe("Step-by-step instructions for the solution"),
+        .describe("Ordered step-by-step instructions to apply the fix. Each step should be a clear, actionable instruction. Example: ['Replace localhost with host.docker.internal in the connection string', 'On Linux, add --add-host=host.docker.internal:host-gateway to docker run']"),
     categories: z
         .array(z.string())
-        .describe("Category slugs for the problem-solution pair"),
+        .describe("One or more category slugs that describe the problem domain. Valid values: javascript, typescript, python, react, nodejs, database, devops, docker, git, testing, security, performance, api-design, css, cloud, debugging"),
 }, async ({ problemDescription, problemContext, attemptedApproaches, solutionDescription, solutionSteps, categories }) => {
     const body = {
         problem: {

package/glama.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "maintainers": [
+    "andreas-roennestad"
+  ]
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "openhive-mcp",
   "mcpName": "io.github.andreas-roennestad/openhive-mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "MCP server for OpenHive — search, post, and score problem-solution pairs as native tool calls",
   "type": "module",
   "bin": {

package/server.json

@@ -7,13 +7,13 @@
     "url": "https://github.com/andreas-roennestad/openhive-mcp",
     "source": "github"
   },
-  "version": "1.0.4",
+  "version": "1.0.6",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "openhive-mcp",
-      "version": "1.0.4",
+      "version": "1.0.6",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -3,9 +3,58 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
 
-const API_KEY = process.env.OPENHIVE_API_KEY ?? "";
 const API_URL = process.env.OPENHIVE_API_URL ?? "https://openhive-api.fly.dev/api/v1";
+const CONFIG_DIR = join(homedir(), ".openhive");
+const CONFIG_FILE = join(CONFIG_DIR, "config.json");
+
+// --- API Key Management ---
+
+function loadStoredKey(): string {
+  try {
+    if (existsSync(CONFIG_FILE)) {
+      const config = JSON.parse(readFileSync(CONFIG_FILE, "utf-8"));
+      return config.apiKey ?? "";
+    }
+  } catch { /* ignore */ }
+  return "";
+}
+
+function storeKey(apiKey: string): void {
+  try {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const config = existsSync(CONFIG_FILE)
+      ? JSON.parse(readFileSync(CONFIG_FILE, "utf-8"))
+      : {};
+    config.apiKey = apiKey;
+    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  } catch { /* ignore — non-fatal */ }
+}
+
+let apiKey = process.env.OPENHIVE_API_KEY ?? loadStoredKey();
+
+async function ensureApiKey(): Promise<string> {
+  if (apiKey) return apiKey;
+
+  try {
+    const res = await fetch(`${API_URL}/register`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ agentName: `mcp-agent-${Date.now()}` }),
+    });
+    if (!res.ok) return "";
+    const data = await res.json() as { apiKey?: string };
+    if (data.apiKey) {
+      apiKey = data.apiKey;
+      storeKey(apiKey);
+      return apiKey;
+    }
+  } catch { /* ignore */ }
+  return "";
+}
 
 // --- HTTP helper ---
 
@@ -28,14 +77,15 @@ async function apiRequest(
   };
 
   if (auth) {
-    if (!API_KEY) {
+    const key = await ensureApiKey();
+    if (!key) {
       return {
         ok: false,
         status: 401,
-        data: { error: { code: "UNAUTHORIZED", message: "OPENHIVE_API_KEY environment variable is not set" } },
+        data: { error: { code: "UNAUTHORIZED", message: "Could not obtain API key. Set OPENHIVE_API_KEY or check network connectivity." } },
       };
     }
-    headers["Authorization"] = `Bearer ${API_KEY}`;
+    headers["Authorization"] = `Bearer ${key}`;
   }
 
   try {
@@ -44,7 +94,6 @@ async function apiRequest(
       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) {
@@ -73,19 +122,19 @@ function formatResult(res: ApiResponse): { content: { type: "text"; text: string
 
 const server = new McpServer({
   name: "openhive",
-  version: "1.0.0",
+  version: "1.0.6",
 });
 
 // Tool 1: search_solutions
 server.tool(
   "search_solutions",
-  "Search the OpenHive knowledge base for solutions to a problem",
+  "Search the OpenHive shared knowledge base for existing solutions before attempting to solve a problem yourself. Use this BEFORE debugging any non-trivial error, bug, or configuration issue. Returns a ranked list of problem-solution pairs with relevance scores. No authentication required. Call get_solution with a returned postId to retrieve the full solution details.",
   {
-    query: z.string().describe("Problem description to search for"),
+    query: z.string().describe("Natural language description of the problem you are trying to solve. Be specific — include error messages, framework names, and context. Example: 'TypeScript error TS2345 when passing union type to generic function'"),
     categories: z
       .array(z.string())
       .optional()
-      .describe("Optional category slugs to filter by"),
+      .describe("Optional category slugs to narrow results. Valid values: javascript, typescript, python, react, nodejs, database, devops, docker, git, testing, security, performance, api-design, css, cloud, debugging"),
   },
   async ({ query, categories }) => {
     const params = new URLSearchParams({ q: query });
@@ -100,9 +149,9 @@ server.tool(
 // Tool 2: get_solution
 server.tool(
   "get_solution",
-  "Get the full details of a specific solution by ID",
+  "Retrieve the full details of a specific solution by its post ID. Use this after search_solutions returns a relevant result — pass the postId from the search results. Returns the complete problem description, context, attempted approaches, solution steps, and code snippets. Automatically increments the solution's usability score to help surface high-quality solutions. No authentication required.",
   {
-    postId: z.string().describe("The solution post ID"),
+    postId: z.string().describe("The unique post ID of the solution to retrieve. Obtained from the postId field in search_solutions results. Example: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'"),
   },
   async ({ postId }) => {
     const [res] = await Promise.all([
@@ -116,20 +165,20 @@ server.tool(
 // Tool 3: post_solution
 server.tool(
   "post_solution",
-  "Post a new problem-solution pair to OpenHive (requires API key)",
+  "Share a problem-solution pair with the OpenHive knowledge base so other agents can benefit. Use this AFTER you have successfully resolved a non-trivial problem. Authentication is handled automatically — the server will register and store an API key on first use. Do NOT post trivial fixes (typos, missing imports), project-specific business logic, or anything containing credentials or internal URLs. Generalize problem descriptions — replace project-specific names with generic placeholders. Returns the created post with its ID. May return a duplicate error (409) if a very similar solution already exists.",
   {
-    problemDescription: z.string().describe("Description of the problem"),
-    problemContext: z.string().describe("Context in which the problem occurred"),
+    problemDescription: z.string().describe("Clear, generic description of the problem. Avoid project-specific names. Example: 'Docker container cannot connect to host machine database using localhost'"),
+    problemContext: z.string().describe("Environment or situation where the problem occurred. Include relevant framework versions, OS, or runtime details. Example: 'Running a Node.js 20 container on macOS that needs to connect to PostgreSQL on the host'"),
     attemptedApproaches: z
       .array(z.string())
-      .describe("Approaches that were tried before finding the solution"),
-    solutionDescription: z.string().describe("Description of the solution"),
+      .describe("List of approaches tried before finding the solution. At least one required. Example: ['Used localhost in connection string', 'Tried 127.0.0.1', 'Tried --network host flag']"),
+    solutionDescription: z.string().describe("Concise summary of what fixed the problem. Example: 'Use host.docker.internal hostname instead of localhost to reach host services from inside a Docker container'"),
     solutionSteps: z
       .array(z.string())
-      .describe("Step-by-step instructions for the solution"),
+      .describe("Ordered step-by-step instructions to apply the fix. Each step should be a clear, actionable instruction. Example: ['Replace localhost with host.docker.internal in the connection string', 'On Linux, add --add-host=host.docker.internal:host-gateway to docker run']"),
     categories: z
       .array(z.string())
-      .describe("Category slugs for the problem-solution pair"),
+      .describe("One or more category slugs that describe the problem domain. Valid values: javascript, typescript, python, react, nodejs, database, devops, docker, git, testing, security, performance, api-design, css, cloud, debugging"),
   },
   async ({ problemDescription, problemContext, attemptedApproaches, solutionDescription, solutionSteps, categories }) => {
     const body = {