RefBase MCP

MCP (Model Context Protocol) server that enables AI assistants in IDEs to interact with RefBase webapp for saving conversations, searching bugs/features, and retrieving project context.

Features

• Conversation Management: Save and search AI conversations

• Bug Tracking: Log bugs and search existing issues

• Feature Solutions: Store and retrieve working implementations

• Project Context: Extract and provide project-specific insights

• Secure Authentication: Permanent API key authentication (no more token expiration!)

• IDE Integration: Works with Cursor, Claude Code, Kiro, and other MCP-compatible IDEs

⚠️ Current Status: RefBase server-side authentication is being fixed. The MCP server code is complete and production-ready. Integration tests are temporarily disabled until RefBase resolves their API key authentication bug.

Related MCP server: repo-memory-mcp

Quick Start

Installation

Currently, you need to clone and build the project locally:

git clone https://github.com/DasMonkey/refbase-mcp.git
cd refbase-mcp
npm install && npm run build
npm start

💡 Global npm package coming soon! Once published to npm, you'll be able to use npm install -g refbase-mcp for simpler setup.

Authentication Setup

Step 1: Generate RefBase API Key

1. Visit RefBase webapp

2. Sign in or create an account

3. Go to Settings → API Keys

4. Click "Create API Key"

5. Give it a descriptive name (e.g., "Kiro IDE", "Cursor IDE", "Claude Code")

6. Copy the API key immediately - it's only shown once!

7. Format will be: refb_a1b2c3d4e5f6789012345678901234ab

⚠️ Important: Save your API key securely - it never expires but can't be viewed again after creation.

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Add your RefBase API key to the .env file:

# Open the .env file in your text editor and ADD this line:
REFBASE_API_KEY=refb_a1b2c3d4e5f6789012345678901234ab

# Replace with your actual API key from Step 1 above

3. Your .env file should contain these key settings:

# Required - Your API key from RefBase
REFBASE_API_KEY=refb_your_actual_api_key_here

# Required - RefBase API endpoint  
REFBASE_API_URL=https://refbase.dev/api

# Optional
MCP_SERVER_PORT=3000
LOG_LEVEL=info

💡 Important: Never commit your .env file to version control - it contains your secret API key!

Step 2: IDE Integration

Choose your IDE and follow the specific setup instructions:

🎯 Kiro IDE

Step 1: Build the Project

cd refbase-mcp
npm install
npm run build
npm start

Step 2: Configure Kiro IDE - JSON Config Use the JSON editor in Kiro and paste this exact config: in Workspace Config.

{
  "mcpServers": {
    "refbase": {
      "name": "RefBase Knowledge Base",
      "command": "node",
      "args": ["/path/to/refbase-mcp/dist/cli.js"],
      "environment": {
        "REFBASE_API_URL": "https://refbase.dev/api",
        "REFBASE_API_KEY": "refb_your_actual_api_key_here",
        "LOG_LEVEL": "info"
      },
      "disabled": false,
      "autoApprove": [
        "mcp_refbase_get_project_context",
        "mcp_refbase_search_conversations",
        "mcp_refbase_save_conversation",
        "mcp_refbase_search_bugs",
        "mcp_refbase_save_bug",
        "mcp_refbase_search_features",
        "mcp_refbase_save_feature",
        "mcp_refbase_setup_project"
      ]
    }
  }
}

Important Notes:

• Replace /path/to/refbase-mcp/dist/cli.js with your actual project path

• Windows example: "C:\\Users\\YourName\\refbase-mcp\\dist\\cli.js" (note double backslashes)

• "disabled": false: Required for Kiro IDE - explicitly enables the MCP server (other IDEs don't need this)

• autoApprove: Pre-approves RefBase tools so AI can use them without permission popups (recommended for better UX)

• Mac/Linux example: "/Users/YourName/refbase-mcp/dist/cli.js"

• Use dist/cli.js not dist/index.js

• Replace refb_your_actual_api_key_here with your actual RefBase API key

Step 3: Save and Test

1. Click "Save" or "Apply"

2. Restart Kiro IDE completely

3. Start a new conversation - RefBase tools should appear!

🖱️ Cursor IDE

Step 1: Open Cursor Settings

1. Open Cursor IDE

2. Press Cmd/Ctrl + , (Settings shortcut)

3. OR go to: Menu → File → Preferences → Settings

Step 2: Find MCP Settings

1. In the Settings search box, type: "MCP"

2. Look for "Extensions" → "MCP Servers"

3. OR navigate to: Extensions → MCP in the left sidebar

Step 3: Add RefBase Server

1. Click "Edit in settings.json" or "Add Server"

2. Copy and paste this exact configuration:

{
  "mcp.servers": {
    "refbase": {
      "command": "node",
      "args": ["/path/to/refbase-mcp/dist/cli.js"],
      "env": {
        "REFBASE_API_URL": "https://refbase.dev/api",
        "REFBASE_API_KEY": "refb_your_actual_api_key_here"
      },
      "autoApprove": [
        "save_conversation",
        "save_feature", 
        "save_bug",
        "search_conversations",
        "search_features",
        "search_bugs",
        "setup_project",
        "get_project_context"
      ]
    }
  }
}

Important: Replace /path/to/refbase-mcp/dist/cli.js with your actual path to the project folder.

💡 autoApprove: Pre-approves RefBase tools so AI can use them without permission popups. Makes conversations flow much smoother!

Path Examples:

• Windows: "C:\\Users\\YourName\\refbase-mcp\\dist\\cli.js"

• Mac/Linux: "/Users/YourName/refbase-mcp/dist/cli.js"

Step 4: Alternative - Project-Level Config

1. In your project folder, create a new file: .cursorrules

2. Paste this exact content:

{
  "mcp": {
    "servers": {
      "refbase": {
        "command": "node",
        "args": ["/path/to/refbase-mcp/dist/cli.js"],
        "env": {
          "REFBASE_API_URL": "https://refbase.dev/api",
          "REFBASE_API_KEY": "refb_your_actual_api_key_here"
        },
        "autoApprove": [
          "save_conversation",
          "save_feature", 
          "save_bug",
          "search_conversations",
          "search_features",
          "search_bugs",
          "setup_project",
          "get_project_context"
        ]
      }
    }
  }
}

Important: Replace /path/to/refbase-mcp/dist/cli.js with your actual path to the project folder.

💡 autoApprove: Pre-approves RefBase tools for seamless AI interactions without permission popups!

Step 5: Save and Restart

1. Save the file (Ctrl+S)

2. Restart Cursor completely

3. Open a new chat and look for RefBase tools

🔧 Claude Code

Step 1: Create MCP Configuration File

1. Open any IDE of your choice

2. In your project root, create a new file named .mcp.json

3. This file will configure MCP servers for this specific project

Step 2: Add RefBase Server Configuration

1. Copy and paste this exact configuration into .mcp.json:

{
  "mcpServers": {
    "refbase": {
      "command": "node",
      "args": ["/path/to/refbase-mcp/dist/cli.js"],
      "env": {
        "REFBASE_API_URL": "https://refbase.dev/api",
        "REFBASE_API_KEY": "refb_your_actual_api_key_here"
      },
      "autoApprove": [
        "save_conversation",
        "save_feature", 
        "save_bug",
        "search_conversations",
        "search_features",
        "search_bugs",
        "setup_project",
        "get_project_context"
      ]
    }
  }
}

Important: Replace /path/to/refbase-mcp/dist/cli.js with your actual path to the project folder.

💡 autoApprove: Pre-approves RefBase tools so Claude can use them without showing permission popups each time. This makes conversations flow much smoother!

Path Examples:

• Windows: "C:\\Users\\YourName\\refbase-mcp\\dist\\cli.js"

• Mac/Linux: "/Users/YourName/refbase-mcp/dist/cli.js"

Step 3: Save and Restart

1. Click "Save" or Ctrl+S

2. Restart Claude Code completely (close and reopen)

3. Wait 10-15 seconds for MCP server to connect

Step 4: Test It Works

1. Start a new conversation in Claude Code

2. Type: "Use the save_conversation tool"

3. You should see RefBase tools appear in the available tools list

4. If you see save_conversation, search_bugs, etc. - it's working! ✅

🔧 Other MCP-Compatible IDEs

For any MCP-compatible IDE:

1. Server Command: refbase-mcp

2. Arguments: ["start"]

3. Port: 3000 (default)

4. Environment Variables:

   • REFBASE_API_URL=https://refbase.dev/api

   • MCP_SERVER_PORT=3000

Step 3: Test Your Setup

Method 1: Ask AI Assistant to Use Tools

1. Start a conversation in your IDE

2. Type this exact message:

   "Please use the save_conversation tool to save our current conversation to RefBase. 
   Use my API key: refb_your_actual_api_key_here"

3. The AI should automatically use the RefBase tools and save the conversation

Method 2: Manual Tool Usage If your IDE shows tools directly, look for these RefBase tools:

• save_conversation - Save current chat

• search_conversations - Find past chats

• save_bug - Log a bug

• search_bugs - Find existing bugs

• save_feature - Store a solution

• search_features - Find implementations

Method 3: Test the Tools Simply ask your AI assistant to use RefBase tools:

📝 "Save this conversation to RefBase with the title 'Testing MCP integration'" 🐛 "Log a bug: Login button not working on mobile"
🔍 "Search RefBase for React hooks conversations"

Step 4: Verify It's Working

1. Go to RefBase webapp

2. Check your saved items:

   • Conversations tab - should see saved chats

   • Bugs tab - should see logged bugs

   • Features tab - should see saved solutions

3. If you see your saved items there, it's working perfectly! ✅

📁 IMPORTANT: Directory Guide

🤔 Confused about where to run commands? Here's the breakdown:

refbase-mcp Directory (This Project)

Location: D:\AI\Cursor projects\refbase-mcp\

• Purpose: Install and configure the MCP server

• Commands to run here:

  npm install && npm run build  # Install MCP server
  npm start                     # Start MCP server (if needed)

• IDE Config: Point your IDE's MCP config to path/to/refbase-mcp/dist/cli.js

Your Actual Project Directory (Where You Code)

Location: D:\MyApp\, C:\Projects\MyReactApp\, etc.

• Purpose: Link your project to RefBase and use MCP tools

• Commands to run here (via AI chat in IDE):

  • setup_project ← Run this in YOUR project

  • save_conversation, save_feature, save_bug

• Rule: Open your IDE in YOUR project directory, then use MCP tools

💡 Summary: Install MCP once in refbase-mcp, then use it in every project you work on.

🚀 Project Setup (First Time Only)

⚠️ CRITICAL: Run setup_project in YOUR PROJECT directory, NOT in refbase-mcp!

After MCP is connected and working, set up your project:

Once you've confirmed MCP tools are working, use the project setup tool to create or link your workspace to RefBase:

1. In any IDE chat conversation, type:

   "Please use the setup_project tool to create a new RefBase project for this workspace"

2. The MCP tool will:

   • Auto-detect your project name, language, framework, and tech stack

   • Present you with setup options

3. Choose your setup option:

   • create_new - Create a brand new RefBase project

   • link_existing - Link to an existing RefBase project

   • configure_manual - Manually set project details

   • skip - Skip setup for now

4. Benefits after setup:

   • All MCP tools automatically know your project context

   • Better search results when finding similar conversations/bugs/features

   • Automatic project categorization and tech stack detection

💡 One-time setup: This only needs to be done once per project. After setup, your workspace is permanently linked to RefBase.

🔗 How to Link to Existing RefBase Project

Need to connect your current workspace to an existing RefBase project? Follow these steps:

Step 1: Get Your Project ID from RefBase Webapp

1. Visit RefBase.dev and sign in

2. Go to your project dashboard - you'll see all your projects listed

3. Find the project you want to link to

4. Click the 3 dots menu (⋯) next to the project name

5. Select "Copy Project ID" from the dropdown menu

   • The Project ID format looks like: ffef03c1-0046-43bc-9c9b-5f0b8617b323

6. Save this ID - you'll need it in the next step

Step 2: Run Project Setup with Existing Project ID

1. Open your IDE in the project directory you want to link (NOT in refbase-mcp)

2. Start a conversation with your AI assistant

3. Run the setup command with your Project ID:

"Use the setup_project tool with action 'link_existing' and existingProjectId 'ffef03c1-0046-43bc-9c9b-5f0b8617b323'"

Replace the example ID with your actual Project ID from Step 1

Step 3: Verify the Connection

1. Look for success message: 🔗 Successfully linked to existing RefBase project

2. Test with a save tool: Try save_conversation or save_feature

3. Check RefBase webapp: Your saved items should now appear in the linked project

Step 4: Troubleshooting

If linking fails:

• ✅ Double-check Project ID - Make sure it's copied correctly

• ✅ Verify project access - Ensure you own or have access to the project

• ✅ Check workspace directory - Make sure you're in YOUR project, not refbase-mcp

• ✅ Try again - Run setup_project again with the correct ID

After successful linking:

• All save_conversation, save_bug, save_feature will be associated with your project

• No more NULL project_id issues!

• Items appear properly in RefBase project dashboard

💡 Pro Tip: Maximum Export Quality

For the best conversation exports with maximum technical context:

1. Ask AI to create a comprehensive summary first:

   "Please create a detailed technical report summarizing all the work we did in this conversation, including:
   - Problems encountered and solutions implemented
   - Code changes made and files modified  
   - Error debugging steps and fixes applied
   - Implementation approaches and decisions made
   - Any patterns or best practices discovered"

2. Then export the summary:

   "Now please use the save_conversation tool to let AI summarize and export this technical report to RefBase"

Why this works better:

• AI creates a structured, comprehensive technical summary

• Captures implementation details often missing from raw conversations

• Includes debugging context, error resolution steps, and decision-making process

• Results in much higher quality knowledge base entries

• Makes future AI searches more effective with better context

🎯 Result: You get detailed technical reports instead of raw chat logs, making your RefBase knowledge base far more valuable for future reference and AI context feeding!

Manual Server Start (Alternative) (not tested yet)

If IDE integration doesn't work, you can run the server manually:

# Start the MCP server directly
refbase-mcp start

# Or with custom configuration  
refbase-mcp start --port 3000 --config ./my-config.json

# Development mode with hot reload
npm run dev

Available MCP Tools

🚨 IMPORTANT: Project Setup Required First!

Before using any save tools, you MUST link your workspace to a RefBase project:

Option 1: Link to Existing Project (Recommended)

1. Get your Project ID from RefBase webapp:

   • Go to your project dashboard at refbase.dev

   • Find your project and click the 3 dots menu (⋯) next to the project name

   • Select "Copy Project ID" or find it in project settings

2. Run setup: Use the setup_project tool with link_existing action and paste your Project ID

Option 2: Create New Project

Use the setup_project tool with create_new action to create a fresh project.

⚠️ Without this setup, conversations/bugs/features will be saved with NULL project_id and won't appear in your project dashboard!

🛠️ Available Tools

All tools are automatically authenticated through your MCP configuration - just call them directly in your IDE!

Conversation Tools

• save_conversation - Save your current AI conversation to RefBase for future reference

• search_conversations - Find similar past conversations by keywords or tags

• get_conversation - Retrieve a specific conversation by ID

Bug Tracking Tools

• save_bug - Log a new bug with symptoms, severity, and context

• search_bugs - Find existing bugs by symptoms or keywords

• update_bug_status - Mark bugs as resolved, in-progress, etc.

• get_bug_details - Get full details about a specific bug

Feature & Solution Tools

• save_feature - Store working code implementations and solutions

• search_features - Find existing implementations for similar features

• get_feature_implementation - Retrieve detailed implementation code

Project Management Tools

• setup_project - REQUIRED FIRST: Link your workspace to a RefBase project

• get_project_context - Get relevant project information and patterns

• search_similar_projects - Find projects with similar technology stacks

• get_project_patterns - Extract common coding patterns from your project

Development

Setup

git clone <repository>
cd refbase-mcp
npm install
npm run build
cp .env.example .env
npm start

Scripts

npm run dev          # Development with hot reload
npm run build        # Build TypeScript
npm run test         # Run tests
npm run lint         # Lint code
npm run format       # Format code

Testing

npm test             # Run all tests
npm run test:watch   # Watch mode

Troubleshooting

Connection Issues

Error: "refbase-mcp is not recognized as an internal or external command"

• Cause: You're using local development setup but config points to global command

• Solution: Update your IDE config to use "command": "node" and "args": ["path/to/dist/cli.js"]

Error: "MCP error -32000: Connection closed"

• Cause: Wrong file path or using index.js instead of cli.js

• Solutions:

  1. Use dist/cli.js not dist/index.js

  2. Check your file path is correct

  3. Run npm run build to ensure dist/cli.js exists

  4. Try using forward slashes: D:/path/to/file instead of D:\\path\\to\\file

Error: API authentication failures

• Cause: Missing or incorrect API key

• Solutions:

  1. Add REFBASE_API_KEY to your IDE environment variables

  2. Verify your API key format: refb_xxxxx...

  3. Check the API key is valid at RefBase.dev

IDE shows "Reconnecting to server" repeatedly

• Cause: MCP server crashes on startup

• Solutions:

  1. Check the MCP server logs for error details

  2. Verify all required environment variables are set

  3. Try running manually: node dist/cli.js to see startup errors

Project Setup Issues

Error: "Conversations/bugs/features saved with NULL project_id"

• Cause: Haven't run setup_project to link workspace to RefBase project

• Solution:

  1. Get Project ID: Go to refbase.dev → Project Dashboard → Click 3 dots menu (⋯) next to project name → Copy Project ID

  2. Link project: Use setup_project tool with link_existing action and paste your Project ID

  3. Alternative: Use setup_project with create_new to create a new project

Error: "Items don't appear in RefBase project dashboard"

• Cause: Items saved without project association (project_id = NULL)

• Solution: Follow project setup steps above, then items will be properly linked to your project

Testing Your Setup

Quick Test Commands:

1. Manual server test: cd refbase-mcp && node dist/cli.js

2. Check if built: Look for dist/cli.js file

3. IDE tool test: In IDE chat, type "Use the save_conversation tool"

Expected Behavior:

• MCP server starts silently (no "listening on port" message)

• IDE shows RefBase tools: save_conversation, search_bugs, etc.

• Tools accept your API key and communicate with RefBase.dev

Configuration Reference

See .env.example for all available configuration options.

License

Apache 2.0