# 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.

## Quick Start

### Installation

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

```bash
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](https://refbase.dev)
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:
```bash
cp .env.example .env
```

2. **Add your RefBase API key to the .env file:**
```bash
# 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:
```bash
# 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**
```bash
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.
```json
{
  "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:**

```json
{
  "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:**

```json
{
  "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`:**

```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](https://refbase.dev)
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**:
  ```bash
  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](https://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:

```bash
# 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](https://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
```bash
git clone <repository>
cd refbase-mcp
npm install
npm run build
cp .env.example .env
npm start
```

### Scripts
```bash
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
```bash
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](https://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](https://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