Hivemind MCP

Instructions

Implementation Reference

• src/api.ts:317-380 (handler)

  Core handler for 'contribute_project' MCP tool. Supports local file storage (.hive.json) or cloud (Supabase). Auto-detects user_id from .user_id file. For cloud, POSTs to /contribute-project endpoint.

  export async function contributeProject(
    userId: string | null,
    projectId: string,
    query: string,
    solution: string,
    category?: string,
    isPublic: boolean = false,
    projectPath?: string
  ): Promise<ContributeProjectResult> {
    // Auto-detect user_id if not provided
    if (!userId) {
      userId = await getUserId(projectPath);
      if (!userId) {
        throw new Error('No .user_id file found. Run init_hive first.');
      }
    }
  
    // Check if local storage
    if (userId.startsWith('local-') && projectPath) {
      const hive = await readLocalHive(projectPath);
      if (!hive) {
        throw new Error('Local hive not found. Run init_hive first.');
      }
  
      const newEntry: LocalHiveEntry = {
        id: hive.entries.length + 1,
        query,
        solution,
        category: category || 'general',
        created_at: new Date().toISOString()
      };
  
      hive.entries.push(newEntry);
      await writeLocalHive(projectPath, hive);
  
      return {
        success: true,
        entry_id: newEntry.id,
        message: `Added to ${projectId} hive (local)`
      };
    }
  
    // Cloud storage - use API
    const response = await fetch(`${API_BASE}/contribute-project`, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        user_id: userId,
        project_id: projectId,
        query,
        solution,
        category,
        is_public: isPublic
      }),
    });
  
    if (!response.ok) {
      throw new Error(`Contribute project failed: ${response.statusText}`);
    }
  
    return response.json();
  }

• src/index.ts:148-185 (schema)

  Tool schema definition including name, description, and inputSchema for validation in MCP ListToolsRequestHandler.

  {
    name: "contribute_project",
    description:
      "Add knowledge to project hive. TRIGGERS: 'add to hive', 'update hive', 'contribute to hive', 'store in hive'. When user says 'update hive', analyze recent work and contribute automatically. When user says 'add to hive', ask what they want to store. Stores solutions, patterns, pitfalls, architecture decisions, etc. Private by default, optionally public. Categories are dynamic - user can create any category name.",
    inputSchema: {
      type: "object",
      properties: {
        user_id: {
          type: "string",
          description: "Optional: User ID (auto-detected from .user_id in cwd if not provided)",
        },
        project_id: {
          type: "string",
          description: "Project identifier",
        },
        query: {
          type: "string",
          description: "Error message or problem description",
        },
        solution: {
          type: "string",
          description: "What fixed it",
        },
        category: {
          type: "string",
          description: "Optional category (auto-detected if not provided)",
        },
        is_public: {
          type: "boolean",
          description: "Make this entry public (default: false/private)",
        },
        project_path: {
          type: "string",
          description: "Optional: Project directory path (required for local storage)",
        },
      },
      required: ["project_id", "query", "solution"],
    },

• src/index.ts:419-432 (handler)

  MCP CallToolRequestSchema switch case dispatcher that extracts arguments and calls the contributeProject handler function.

  case "contribute_project": {
    const result = await contributeProject(
      args?.user_id as string,
      args?.project_id as string,
      args?.query as string,
      args?.solution as string,
      args?.category as string | undefined,
      args?.is_public as boolean | undefined,
      args?.project_path as string | undefined
    );
    return {
      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
    };
  }

• supabase/functions/public/index.ts:469-527 (handler)

  Backend Supabase Edge Function handler for HTTP POST /contribute-project. Validates input, inserts new knowledge entry into 'knowledge_entries' table with project-specific fields.

  async function handleContributeProject(supabase: any, body: any, corsHeaders: any) {
    const { user_id, project_id, query, solution, category, is_public = false } = body;
  
    if (!user_id || !project_id || !query || !solution) {
      return new Response(JSON.stringify({ error: 'user_id, project_id, query, and solution required' }), {
        status: 400,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' }
      });
    }
  
    // Get project name from first entry or use project_id as fallback
    const { data: existingEntry } = await supabase
      .from('knowledge_entries')
      .select('project_name')
      .eq('user_id', user_id)
      .eq('project_id', project_id)
      .limit(1)
      .single();
  
    const project_name = existingEntry?.project_name || project_id;
  
    // Insert project knowledge entry (solutions is JSONB array)
    const { data, error } = await supabase
      .from('knowledge_entries')
      .insert({
        user_id,
        project_id,
        project_name,
        query,
        solutions: [{
          solution,
          success_rate: null,
          command: null,
          note: null
        }],
        category: category || 'general',
        is_public,
        type: 'fix'
      })
      .select()
      .single();
  
    if (error) {
      console.error('Contribute project error:', error);
      return new Response(JSON.stringify({ error: 'Failed to store project knowledge' }), {
        status: 500,
        headers: { ...corsHeaders, 'Content-Type': 'application/json' }
      });
    }
  
    return new Response(JSON.stringify({
      success: true,
      entry_id: data.id,
      message: `Added to ${project_name} KB${is_public ? ' (public)' : ' (private)'}`,
      _ctx: "HIVE COMPOUNDS: Bigger hive = smarter Claude, less re-explaining. CONTRIBUTE AFTER WORK: Add solutions, patterns, pitfalls when done."
    }), {
      headers: { ...corsHeaders, 'Content-Type': 'application/json' }
    });
  }

• supabase/functions/public/index.ts:102-103 (registration)

  HTTP route registration in Supabase public gateway switch that directs /contribute-project requests to handleContributeProject.

  case 'contribute-project':
    return await handleContributeProject(supabase, body, corsHeaders);