# Integration Guide - Project Mind MCP with Claude Desktop

Complete guide for integrating Project Mind MCP with Claude Desktop.

---

## 📋 Prerequisites

Before starting, ensure you have:

- ✅ Node.js 18 or higher installed
- ✅ Claude Desktop app installed
- ✅ Basic command line knowledge
- ✅ Text editor (VS Code recommended)

### Check Prerequisites

```bash
# Check Node.js version (should be 18+)
node --version

# Check npm version
npm --version

# Check Claude Desktop installation
# Windows: Check C:\Users\<YourName>\AppData\Local\Programs\Claude
# macOS: Check /Applications/Claude.app
# Linux: Check ~/.local/share/Claude
```

---

## 🚀 Step-by-Step Integration

### Step 1: Install Project Mind MCP

```bash
# Clone repository
cd "D:/Project Mind"
git clone https://github.com/yourusername/project-mind-mcp.git
cd project-mind-mcp

# Install dependencies
npm install

# Build TypeScript to JavaScript
npm run build

# Verify build succeeded
ls dist/index.js  # Should exist
```

**Expected output:**
```
dist/
├── index.js
├── filesystem/
├── intelligence/
└── ...
```

### Step 2: Locate Claude Desktop Configuration

**Windows:**
```
%APPDATA%\Claude\claude_desktop_config.json
```
Full path: `C:\Users\<YourName>\AppData\Roaming\Claude\claude_desktop_config.json`

**macOS:**
```
~/Library/Application Support/Claude/claude_desktop_config.json
```

**Linux:**
```
~/.config/Claude/claude_desktop_config.json
```

### Step 3: Configure MCP Server

Open `claude_desktop_config.json` in a text editor.

**If file doesn't exist:** Create it with this content:

```json
{
  "mcpServers": {
    "project-mind": {
      "command": "node",
      "args": [
        "D:/Project Mind/project-mind-mcp/dist/index.js"
      ]
    }
  }
}
```

**If file exists:** Add Project Mind to the `mcpServers` object:

```json
{
  "mcpServers": {
    "existing-server": {
      "command": "...",
      "args": ["..."]
    },
    "project-mind": {
      "command": "node",
      "args": [
        "D:/Project Mind/project-mind-mcp/dist/index.js"
      ]
    }
  }
}
```

**⚠️ Important Notes:**
- Use **forward slashes** (`/`) not backslashes (`\`) in the path
- Use **absolute paths** - relative paths will not work
- Adjust the path to match your actual installation location
- Ensure proper JSON syntax (commas, quotes, brackets)

### Step 4: Restart Claude Desktop

**Complete restart required:**

1. **Quit Claude Desktop completely**
   - Windows: Right-click system tray icon → Quit
   - macOS: Cmd+Q or Claude menu → Quit
   - Linux: Close all windows and quit from system tray

2. **Wait 5 seconds**

3. **Start Claude Desktop again**

### Step 5: Verify Connection

Open a new conversation in Claude Desktop and type:

```
Can you check if Project Mind MCP is connected?
```

**Expected response:**
Claude should confirm connection and may list some or all of the 41 available tools.

---

## 🧪 Test Tool Functionality

### Test 1: Session Management

```
Use Project Mind to check if we need to resume any work
```

**Expected:** 
```
No incomplete sessions detected. Starting fresh.
```

### Test 2: Project Registration

```
Register a test project:
- ID: "test-project"  
- Name: "Test Project"
- Path: "C:/Projects/test"
```

**Expected:**
```
✅ Project "test-project" registered successfully
- ID: test-project
- Name: Test Project
- Path: C:/Projects/test
```

### Test 3: File Operations

```
Create a test file using Project Mind:
- Project: "test-project"
- Path: "test.txt"
- Content: "Hello from Project Mind!"
```

**Expected:**
File created and confirmation message.

### Test 4: Semantic Search

```
Index the test project and search for "hello"
```

**Expected:**
Search results showing the test file.

---

## 🔧 Configuration Options

### Environment Variables

Create a `.env` file in the project root:

```env
# Database location
PROJECT_MIND_DB_PATH=./data/project-mind.db

# Logging level (error, warn, info, debug)
PROJECT_MIND_LOG_LEVEL=info

# Enable performance profiling
PROJECT_MIND_PROFILE=false

# Maximum file size for semantic indexing (MB)
PROJECT_MIND_MAX_FILE_SIZE=10
```

### Project-Specific Configuration

When registering projects, you can customize behavior:

```typescript
pm_register_project({
  id: "my-project",
  name: "My Project",
  path: "C:/Projects/my-project",
  config: {
    fileScanning: {
      enabled: true,
      mode: "auto",        // "manual" | "auto" | "watcher"
      excludes: [
        "**/node_modules/**",
        "**/.git/**",
        "**/dist/**",
        "**/build/**",
        "**/.next/**"
      ]
    },
    git: {
      enabled: true,
      autoCommit: false,
      messageTemplate: "{{type}}({{scope}}): {{message}}"
    },
    backlog: {
      indexPath: "BACKLOG_INDEX.json",
      overviewPath: "BACKLOG_OVERVIEW.md",
      epicsDir: "docs/epics"
    }
  }
});
```

---

## 🐛 Troubleshooting

### Problem: MCP Server Not Showing Up

**Symptoms:**
- Claude doesn't recognize Project Mind commands
- No tools available
- "I don't have access to that" errors

**Solutions:**

1. **Check configuration file syntax**
```bash
# Validate JSON
node -e "console.log(JSON.parse(require('fs').readFileSync('C:\\Users\\YourName\\AppData\\Roaming\\Claude\\claude_desktop_config.json')))"
```

2. **Verify file paths are correct**
   - Use absolute paths
   - Use forward slashes
   - Check file actually exists: `ls "D:/Project Mind/project-mind-mcp/dist/index.js"`

3. **Check Node.js is accessible**
```bash
# Should show Node.js version
node --version
```

4. **Check MCP logs**
   - Windows: `%APPDATA%\Claude\logs\mcp.log`
   - macOS: `~/Library/Logs/Claude/mcp.log`
   - Linux: `~/.local/share/Claude/logs/mcp.log`

5. **Rebuild MCP server**
```bash
cd "D:/Project Mind/project-mind-mcp"
npm run build
```

### Problem: Tools Available But Not Working

**Symptoms:**
- Tools show up but return errors
- Database errors
- Permission errors

**Solutions:**

1. **Check database directory exists**
```bash
cd "D:/Project Mind/project-mind-mcp"
mkdir -p data
```

2. **Check file permissions**
```bash
# Ensure MCP server can write to database
ls -la data/
```

3. **Check project paths are valid**
   - Registered project paths must exist
   - Use absolute paths
   - Windows: Use `C:/` not `C:\`

4. **Clear database and restart** (if corrupted)
```bash
cd "D:/Project Mind/project-mind-mcp"
rm data/project-mind.db
# Restart Claude Desktop
```

### Problem: Slow Performance

**Symptoms:**
- Tools take long to respond
- Semantic search is slow
- Indexing takes forever

**Solutions:**

1. **Check file count**
```
Get project status for "my-project"
```
If >100,000 files, add more excludes to config

2. **Reindex with exclusions**
```typescript
pm_index_files({
  project: "my-project",
  reindex: true
});
```

3. **Check database size**
```bash
ls -lh data/project-mind.db
```
If >100MB, consider clearing old session state

4. **Enable profiling to identify bottleneck**
```env
PROJECT_MIND_PROFILE=true
```

### Problem: Session Recovery Not Working

**Symptoms:**
- check_resume_needed always returns false
- Checkpoints not saving
- Lost context after crash

**Solutions:**

1. **Verify auto_checkpoint is being called**
   - Should be called every 5-10 tool uses
   - Check with status query

2. **Check database isn't readonly**
```bash
ls -la data/project-mind.db
```

3. **Manually trigger checkpoint**
```
Save session state for "my-project"
```

4. **Check session wasn't marked complete prematurely**

---

## 📊 Monitoring & Diagnostics

### Check MCP Server Status

```
List all registered projects
```

### View Performance Metrics

```
Get project status for "my-project"
```

**Expected output:**
```typescript
{
  project: "my-project",
  total: 13,
  byStatus: {
    backlog: 5,
    complete: 8
  },
  byPriority: {
    P1: 3,
    P2: 8,
    P3: 2
  },
  estimatedHours: 117,
  actualHours: 3,
  velocity: 39
}
```

### Check Semantic Index Status

```
Check index status for "my-project"
```

**Expected output:**
```typescript
{
  indexed: true,
  fileCount: 234,
  lastIndexed: "2026-01-07T19:30:00Z",
  indexSize: "2.3MB"
}
```

---

## 🔒 Security Considerations

### File Access

Project Mind has full file system access within registered project directories.

**Best practices:**
- Only register projects you trust
- Review project paths carefully
- Use file exclusions to prevent indexing sensitive files
- Database is stored locally (not cloud-synced)

### Database Security

The SQLite database contains:
- Session state
- Project metadata
- Pattern records
- Research history

**Location:** `D:/Project Mind/project-mind-mcp/data/project-mind.db`

**To backup:**
```bash
cp data/project-mind.db data/project-mind-backup.db
```

**To clear all data:**
```bash
rm data/project-mind.db
# Restart Claude Desktop
```

---

## 🎓 Next Steps

### 1. Register Your Real Projects

```typescript
pm_register_project({
  id: "my-real-project",
  name: "My Real Project",
  path: "C:/Projects/my-real-project",
  config: {
    fileScanning: { mode: "auto" },
    git: { enabled: true }
  }
});
```

### 2. Index Files for Semantic Search

```typescript
pm_index_files({
  project: "my-real-project"
});
```

### 3. Start Using Session Checkpoints

Begin your work session with:
```typescript
auto_checkpoint({
  project: "my-real-project",
  operation: "Your task description",
  progress: 0.0,
  currentStep: "Starting",
  decisions: [],
  nextSteps: ["Step 1", "Step 2"],
  activeFiles: []
});
```

### 4. Explore Pattern Learning

Record successful solutions:
```typescript
record_pattern({
  name: "Your Pattern Name",
  problem: "Problem it solves",
  solution: "High-level solution",
  implementation: "Implementation details",
  project: "my-real-project"
});
```

---

## 📚 Additional Resources

- **Full Tool Reference:** [docs/TOOL_REFERENCE.md](TOOL_REFERENCE.md)
- **Architecture Overview:** [docs/ARCHITECTURE.md](ARCHITECTURE.md)
- **API Documentation:** [docs/API.md](API.md)
- **Examples:** [examples/](../examples/)

---

## 🆘 Getting Help

If you encounter issues not covered here:

1. Check the [GitHub Issues](https://github.com/yourusername/project-mind-mcp/issues)
2. Review MCP logs for error details
3. Create a new issue with:
   - Operating system
   - Node.js version
   - Error message
   - MCP log excerpt

---

**Integration complete! You now have persistent AI intelligence.** 🎉