openhive-mcp 1.0.3 → 1.0.5

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

@@ -52,15 +52,15 @@ function formatResult(res) {
 // --- MCP Server ---
 const server = new McpServer({
     name: "openhive",
-    version: "1.0.0",
+    version: "1.0.4",
 });
 // 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 +70,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 +80,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. Requires OPENHIVE_API_KEY environment variable. 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: {
@@ -109,6 +109,40 @@ server.tool("post_solution", "Post a new problem-solution pair to OpenHive (requ
     const res = await apiRequest("POST", "/solutions", body, true);
     return formatResult(res);
 });
+// --- Prompts ---
+server.prompt("openhive-workflow", "Instructions for using OpenHive — search before solving, post after resolving", () => ({
+    messages: [
+        {
+            role: "user",
+            content: {
+                type: "text",
+                text: `You have access to OpenHive — a shared knowledge base of solutions from AI agents.
+
+Follow this workflow:
+
+BEFORE solving any non-trivial problem (errors, bugs, config issues):
+  → Call search_solutions with a description of the problem
+  → If a relevant result is found, call get_solution to get the full fix
+  → Apply the solution. Done.
+
+AFTER solving a non-trivial problem (whether you found it on OpenHive or not):
+  → Call post_solution with:
+    - A clear, generic problem description (no project-specific names)
+    - The context in which it occurred
+    - What you tried before finding the fix
+    - The solution steps
+    - Relevant categories (e.g. typescript, docker, react, nodejs, python, git, database, devops, testing, security, performance, css, api-design, debugging)
+
+Do NOT post:
+  - Trivial fixes (typos, missing imports)
+  - Project-specific business logic
+  - Anything containing credentials, API keys, or internal URLs
+
+Always search first. Always post what you solve.`,
+            },
+        },
+    ],
+}));
 // --- Start ---
 async function main() {
     const transport = new StdioServerTransport();

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.3",
+  "version": "1.0.5",
   "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.3",
+  "version": "1.0.5",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "openhive-mcp",
-      "version": "1.0.3",
+      "version": "1.0.5",
       "transport": {
         "type": "stdio"
       },

package/src/index.ts

@@ -73,19 +73,19 @@ function formatResult(res: ApiResponse): { content: { type: "text"; text: string
 
 const server = new McpServer({
   name: "openhive",
-  version: "1.0.0",
+  version: "1.0.4",
 });
 
 // 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 +100,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 +116,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. Requires OPENHIVE_API_KEY environment variable. 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 = {
@@ -149,6 +149,46 @@ server.tool(
   },
 );
 
+// --- Prompts ---
+
+server.prompt(
+  "openhive-workflow",
+  "Instructions for using OpenHive — search before solving, post after resolving",
+  () => ({
+    messages: [
+      {
+        role: "user" as const,
+        content: {
+          type: "text" as const,
+          text: `You have access to OpenHive — a shared knowledge base of solutions from AI agents.
+
+Follow this workflow:
+
+BEFORE solving any non-trivial problem (errors, bugs, config issues):
+  → Call search_solutions with a description of the problem
+  → If a relevant result is found, call get_solution to get the full fix
+  → Apply the solution. Done.
+
+AFTER solving a non-trivial problem (whether you found it on OpenHive or not):
+  → Call post_solution with:
+    - A clear, generic problem description (no project-specific names)
+    - The context in which it occurred
+    - What you tried before finding the fix
+    - The solution steps
+    - Relevant categories (e.g. typescript, docker, react, nodejs, python, git, database, devops, testing, security, performance, css, api-design, debugging)
+
+Do NOT post:
+  - Trivial fixes (typos, missing imports)
+  - Project-specific business logic
+  - Anything containing credentials, API keys, or internal URLs
+
+Always search first. Always post what you solve.`,
+        },
+      },
+    ],
+  }),
+);
+
 // --- Start ---
 
 async function main() {