claudetools/MCP_SERVERS.md

# MCP Servers Configuration for ClaudeTools

**Last Updated:** 2026-01-22
**Status:** Configured and Ready for Testing
**Phase:** Phase 1 - Core MCP Servers + GrepAI Integration

---

## Overview

This document describes the Model Context Protocol (MCP) servers configured for the ClaudeTools project. MCP servers extend Claude Code's capabilities by providing specialized tools and integrations.

**What is MCP?**
Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to LLMs, allowing AI applications to connect with various data sources and tools in a consistent manner.

**Official Resources:**
- MCP Registry: https://registry.modelcontextprotocol.io/
- Official GitHub: https://github.com/modelcontextprotocol/servers
- Documentation: https://modelcontextprotocol.io/
- Claude Code MCP Docs: https://code.claude.com/docs/en/mcp

---

## Installed MCP Servers

### 1. GitHub MCP Server

**Package:** `@modelcontextprotocol/server-github`
**Purpose:** Repository management, PR operations, and GitHub API integration
**Status:** Configured (requires GitHub Personal Access Token)

**Capabilities:**
- Repository management (create, clone, fork)
- File operations (read, write, push)
- Branch management (create, list, switch)
- Git operations (commit, push, pull)
- Issues handling (create, list, update, close)
- Pull request management (create, review, merge)
- Search functionality (code, issues, repositories)

**Configuration:**
```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN_HERE>"
    }
  }
}
```

**Setup Steps:**

1. **Generate GitHub Personal Access Token:**
   - Go to: https://github.com/settings/tokens
   - Click "Generate new token (classic)"
   - Select scopes: `repo`, `workflow`, `read:org`, `read:user`
   - Copy the generated token

2. **Add Token to Configuration:**
   - Edit `D:\ClaudeTools\.mcp.json`
   - Replace `<YOUR_TOKEN_HERE>` with your actual token
   - **IMPORTANT:** Do NOT commit the token to version control
   - Consider using environment variables or secrets management

3. **Restart Claude Code** to load the new configuration

**Gitea Integration Notes:**
- The official GitHub MCP server is designed for GitHub.com
- For self-hosted Gitea integration, you may need:
  - Custom MCP server or adapter
  - Gitea API endpoint configuration
  - Alternative authentication method
- See "Future Gitea Integration" section below

---

### 2. Filesystem MCP Server

**Package:** `@modelcontextprotocol/server-filesystem`
**Purpose:** Enhanced file system operations with safety controls
**Status:** Configured and Ready

**Capabilities:**
- Read files with proper permissions
- Write files with safety checks
- Directory management (create, list, delete)
- File metadata access (size, modified time, permissions)
- Search files and directories
- Move and copy operations
- Sandboxed directory access

**Configuration:**
```json
{
  "filesystem": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "D:\\ClaudeTools"
    ]
  }
}
```

**Access Control:**
- Currently restricted to: `D:\ClaudeTools`
- Add additional directories by appending paths to `args` array
- Example for multiple directories:
  ```json
  "args": [
    "-y",
    "@modelcontextprotocol/server-filesystem",
    "D:\\ClaudeTools",
    "D:\\Projects",
    "C:\\Users\\YourUser\\Documents"
  ]
  ```

**Safety Features:**
- Directory access control (only specified directories)
- Permission validation before operations
- Read-only mode available (mount with `:ro` flag in Docker)
- Prevents accidental system file modifications

**Usage Examples:**
- Read project files with context awareness
- Safe file modifications with backups
- Directory structure analysis
- File search across allowed directories

---

### 3. Sequential Thinking MCP Server

**Package:** `@modelcontextprotocol/server-sequential-thinking`
**Purpose:** Structured problem-solving and step-by-step analysis
**Status:** Configured and Ready

**Capabilities:**
- Step-by-step thinking process
- Problem decomposition
- Logical reasoning chains
- Complex analysis structuring
- Decision tree navigation
- Multi-step task planning

**Configuration:**
```json
{
  "sequential-thinking": {
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-sequential-thinking"
    ]
  }
}
```

**Optional Configuration:**
- Disable thought logging: Set environment variable `DISABLE_THOUGHT_LOGGING=true`
- Example:
  ```json
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"],
    "env": {
      "DISABLE_THOUGHT_LOGGING": "true"
    }
  }
  ```

**Usage Scenarios:**
- Complex debugging sessions
- Architecture design decisions
- Multi-step refactoring plans
- Problem diagnosis
- Performance optimization planning

---

### 4. GrepAI MCP Server (Semantic Code Search)

**Package:** `grepai` (standalone binary)
**Purpose:** AI-powered semantic code search and call graph analysis
**Status:** Configured and Indexing Complete
**Version:** v0.19.0

**Capabilities:**
- Semantic code search (find code by what it does, not just text matching)
- Natural language queries ("authentication flow", "database connection pool")
- Call graph analysis (trace function callers/callees)
- Symbol extraction and indexing
- Real-time file watching and automatic re-indexing
- JSON output for AI agent integration

**Configuration:**
```json
{
  "grepai": {
    "command": "D:\\ClaudeTools\\grepai.exe",
    "args": [
      "mcp-serve"
    ]
  }
}
```

**MCP Tools Available:**
- `grepai_search` - Semantic code search with natural language
- `grepai_trace_callers` - Find all functions that call a specific function
- `grepai_trace_callees` - Find all functions called by a specific function
- `grepai_trace_graph` - Build complete call graph for a function
- `grepai_index_status` - Check index health and statistics

**Setup Steps:**

1. **Install GrepAI Binary:**
   ```bash
   curl -L -o grepai.zip https://github.com/yoanbernabeu/grepai/releases/download/v0.19.0/grepai_0.19.0_windows_amd64.zip
   powershell -Command "Expand-Archive -Path grepai.zip -DestinationPath . -Force"
   ```

2. **Install Ollama (if not already installed):**
   - Download from: https://ollama.com/download
   - Ollama provides local, privacy-first embedding generation

3. **Pull Embedding Model:**
   ```bash
   ollama pull nomic-embed-text
   ```

4. **Initialize GrepAI in Project:**
   ```bash
   cd D:\ClaudeTools
   ./grepai.exe init
   # Select: 1) ollama (recommended)
   # Select: 1) gob (file-based storage)
   ```

5. **Start Background Watcher:**
   ```bash
   ./grepai.exe watch --background
   ```
   Note: Initial indexing takes 5-10 minutes for large codebases. The watcher runs continuously and updates the index when files change.

6. **Add to .mcp.json** (already done)

7. **Restart Claude Code** to load the MCP server

**Index Statistics (ClaudeTools):**
- Files indexed: 957
- Code chunks: 6,467
- Symbols extracted: 1,842
- Index size: ~50 MB
- Indexing time: ~5 minutes (initial scan)
- Backend: GOB (file-based)
- Embedding model: nomic-embed-text (768 dimensions)

**Configuration Details:**
- Config file: `.grepai/config.yaml`
- Index storage: `.grepai/` directory
- Log directory: `C:\Users\<username>\AppData\Local\grepai\logs\`
- Ignored patterns: node_modules, venv, .git, dist, etc.

**Search Boost (Enabled):**
GrepAI automatically adjusts relevance scores:
- Source files (`/src/`, `/lib/`, `/app/`): 1.1x boost
- Test files (`_test.`, `.spec.`): 0.5x penalty
- Mock files (`/mocks/`): 0.4x penalty
- Generated files: 0.4x penalty
- Documentation (`.md`): 0.6x penalty

**Usage Examples:**

**Semantic Search:**
```bash
# CLI usage
./grepai.exe search "authentication JWT token" -n 5

# JSON output (used by MCP)
./grepai.exe search "database connection pool" --json -c -n 3
```

**Call Graph Tracing:**
```bash
# Find who calls this function
./grepai.exe trace callers "verify_token"

# Find what this function calls
./grepai.exe trace callees "create_user"

# Full call graph
./grepai.exe trace graph "process_request" --depth 3
```

**Check Index Status:**
```bash
./grepai.exe status
```

**In Claude Code (via MCP):**
After restarting Claude Code, you can use natural language:
- "Use grepai to search for authentication code"
- "Find all functions that call verify_token"
- "Search for database connection handling"
- "What code handles JWT token generation?"

**Performance:**
- Search latency: <100ms (typical)
- Indexing speed: ~200 files/minute
- Memory usage: ~100-200 MB (watcher + index)
- No internet connection required (fully local)

**Privacy & Security:**
- All embeddings generated locally via Ollama
- No data sent to external services
- Index stored locally in `.grepai/` directory
- Safe to use with proprietary code

**Troubleshooting:**

**Issue: No results found**
- Wait for initial indexing to complete (check `./grepai.exe status`)
- Verify watcher is running: `./grepai.exe watch --status`
- Check logs: `C:\Users\<username>\AppData\Local\grepai\logs\grepai-watch.log`

**Issue: Slow indexing**
- Ensure Ollama is running: `curl http://localhost:11434/api/tags`
- Check CPU usage (embedding generation is CPU-intensive)
- Consider reducing chunking size in `.grepai/config.yaml`

**Issue: Watcher won't start**
- Check if another instance is running: `./grepai.exe watch --status`
- Kill stale process (Windows Task Manager)
- Delete `.grepai/watch.pid` if stuck

**Issue: MCP server not responding**
- Verify grepai.exe path in `.mcp.json` is correct
- Restart Claude Code completely
- Test MCP server manually: `./grepai.exe mcp-serve` (should start server)

**Advanced Configuration:**

Edit `.grepai/config.yaml` for customization:

```yaml
embedder:
  provider: ollama           # ollama | lmstudio | openai
  model: nomic-embed-text
  endpoint: http://localhost:11434
  dimensions: 768

store:
  backend: gob              # gob | postgres | qdrant

chunking:
  size: 512                 # Tokens per chunk
  overlap: 50               # Overlap between chunks

search:
  boost:
    enabled: true           # Enable relevance boosting
  hybrid:
    enabled: false          # Combine vector + text search
    k: 60                   # RRF parameter

trace:
  mode: fast                # fast (regex) | precise (tree-sitter)
```

**References:**
- GitHub Repository: https://github.com/yoanbernabeu/grepai
- Documentation: https://yoanbernabeu.github.io/grepai/
- MCP Integration Guide: https://yoanbernabeu.github.io/grepai/mcp/
- Release Notes: https://github.com/yoanbernabeu/grepai/releases

---

## Installation Details

### Prerequisites

- **Node.js:** v24.11.0 (installed)
- **npm/npx:** Included with Node.js
- **Claude Code:** Latest version with MCP support

### Installation Method

All three MCP servers use **npx** for installation, which:
- Downloads packages on-demand (no manual npm install needed)
- Automatically updates to latest versions
- Runs in isolated environments
- Requires no global installations

### Configuration File Location

**Project-Scoped Configuration:**
- File: `D:\ClaudeTools\.mcp.json`
- Scope: ClaudeTools project only
- Version Control: Can be committed (without secrets)
- Team Sharing: Configuration shared across team

**User-Scoped Configuration:**
- File: `~/.claude.json` (C:\Users\YourUser\.claude.json on Windows)
- Scope: All Claude Code projects for current user
- Not shared: User-specific settings

**Recommendation:** Use project-scoped `.mcp.json` for team consistency, but store sensitive tokens in user-scoped config or environment variables.

---

## Testing MCP Servers

### Test 1: Sequential Thinking Server

**Test Command:**
```bash
npx -y @modelcontextprotocol/server-sequential-thinking --help
```

**Expected:** Server runs without errors

**In Claude Code:**
- Ask: "Use sequential thinking to break down the problem of optimizing database queries"
- Verify: Claude provides step-by-step analysis

---

### Test 2: Filesystem Server

**Test Command:**
```bash
npx -y @modelcontextprotocol/server-filesystem --help
```

**Expected:** Server runs without errors

**In Claude Code:**
- Ask: "List all Python files in the api directory"
- Ask: "Read the contents of api/main.py and summarize"
- Verify: Claude can access files in D:\ClaudeTools

---

### Test 3: GitHub Server

**Test Command:**
```bash
npx -y @modelcontextprotocol/server-github --help
```

**Expected:** Server runs without errors

**In Claude Code (after adding token):**
- Ask: "List my recent GitHub repositories"
- Ask: "Show me open pull requests for ClaudeTools"
- Verify: Claude can access GitHub API

**Note:** Requires valid `GITHUB_PERSONAL_ACCESS_TOKEN` in configuration

---

### Test 4: GrepAI Semantic Search

**Test Command:**
```bash
./grepai.exe search "authentication" -n 3
```

**Expected:** Returns 3 relevant code chunks related to authentication

**Check Index Status:**
```bash
./grepai.exe status
```

**Expected:** Shows indexed files count, chunks, and index size

**In Claude Code (after restart):**
- Ask: "Use grepai to search for database connection code"
- Ask: "Find all functions that call verify_token"
- Verify: Claude can perform semantic code search

**Note:** GrepAI requires Ollama to be running with nomic-embed-text model

---

## Troubleshooting

### Issue: MCP Servers Not Appearing in Claude Code

**Solutions:**
1. Verify `.mcp.json` syntax (valid JSON)
2. Restart Claude Code completely (quit and relaunch)
3. Check Claude Code logs for errors
4. Verify npx works: `npx --version`

---

### Issue: GitHub MCP Server - Authentication Failed

**Solutions:**
1. Verify token is correct in `.mcp.json`
2. Check token scopes include: `repo`, `workflow`, `read:org`
3. Test token manually:
   ```bash
   curl -H "Authorization: token YOUR_TOKEN" https://api.github.com/user
   ```
4. Regenerate token if expired

---

### Issue: Filesystem MCP Server - Access Denied

**Solutions:**
1. Verify directory path in configuration matches actual path
2. Check Windows path format: `D:\\ClaudeTools` (double backslashes)
3. Ensure directory exists and is readable
4. Add additional directories to `args` array if needed

---

### Issue: Sequential Thinking Server - No Output

**Solutions:**
1. Explicitly ask Claude to "use sequential thinking"
2. Check if `DISABLE_THOUGHT_LOGGING=true` is set
3. Try with a complex problem that requires multi-step reasoning

---

## Security Considerations

### GitHub Token Security

**DO:**
- Use fine-grained tokens with minimal required scopes
- Store tokens in environment variables or secrets manager
- Rotate tokens regularly (every 90 days)
- Use separate tokens for different environments

**DO NOT:**
- Commit tokens to version control
- Share tokens in team chat or documentation
- Use admin-level tokens for routine operations
- Store tokens in plaintext configuration files (committed to git)

**Best Practice:**
```json
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": {
      "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
    }
  }
}
```
Then set `GITHUB_TOKEN` environment variable in your shell or user config.

---

### Filesystem Access Control

**Current Configuration:**
- Access limited to: `D:\ClaudeTools`
- Prevents accidental system file modifications
- Safe for automated operations

**Adding Directories:**
- Only add directories that Claude Code should access
- Avoid adding system directories (C:\Windows, etc.)
- Consider read-only access for sensitive directories

---

## Future Gitea Integration

### Current Status

The GitHub MCP server (`@modelcontextprotocol/server-github`) is designed for GitHub.com and may not work directly with self-hosted Gitea instances.

### Integration Options

**Option 1: Custom MCP Server for Gitea**
- Create custom MCP server using Gitea API
- Based on MCP Python SDK or TypeScript SDK
- Full control over authentication and features
- Effort: High (development required)

**Option 2: GitHub MCP Server with Adapter**
- Modify GitHub MCP server to support Gitea endpoints
- Fork `@modelcontextprotocol/server-github`
- Update API endpoints to point to Gitea instance
- Effort: Medium (modification required)

**Option 3: Generic Git MCP Server**
- Use git CLI-based MCP server
- Works with any git remote (including Gitea)
- Limited to git operations (no PR/issue management)
- Effort: Low (may already exist)

### Required Gitea Configuration

For any Gitea integration, you'll need:

1. **Gitea Access Token:**
   - Generate from: `https://your-gitea-instance.com/user/settings/applications`
   - Required scopes: `repo`, `user`, `api`

2. **API Endpoint:**
   - Gitea API: `https://your-gitea-instance.com/api/v1`
   - Compatible with GitHub API v3 (mostly)

3. **Environment Variables:**
   ```json
   "env": {
     "GITEA_TOKEN": "your-gitea-token",
     "GITEA_HOST": "https://your-gitea-instance.com",
     "GITEA_API_URL": "https://your-gitea-instance.com/api/v1"
   }
   ```

### Next Steps for Gitea Integration

1. Research existing Gitea MCP servers in registry
2. Evaluate GitHub MCP compatibility with Gitea API
3. Consider developing custom Gitea MCP server
4. Document Gitea-specific configuration
5. Test with Gitea instance

**Recommendation:** Start with Option 3 (Generic Git MCP) for basic operations, then evaluate custom development for full Gitea API integration.

---

## Additional MCP Servers (Future Consideration)

### Potential Phase 2 Servers

1. **Database MCP Server**
   - Direct MariaDB/MySQL integration
   - Query execution and schema inspection
   - Useful for ClaudeTools database operations

2. **Docker MCP Server**
   - Container management
   - Image operations
   - Useful for deployment automation

3. **Slack MCP Server**
   - Team notifications
   - Integration with work tracking
   - Useful for status updates

4. **Browser Automation MCP**
   - Playwright/Puppeteer integration
   - Testing and scraping
   - Useful for web-based testing

---

## References and Resources

### Official Documentation
- MCP Specification: https://modelcontextprotocol.io/specification/2025-11-25
- MCP Registry: https://registry.modelcontextprotocol.io/
- Claude Code MCP Guide: https://code.claude.com/docs/en/mcp

### Package Documentation
- GitHub MCP: https://www.npmjs.com/package/@modelcontextprotocol/server-github
- Filesystem MCP: https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem
- Sequential Thinking MCP: https://www.npmjs.com/package/@modelcontextprotocol/server-sequential-thinking

### Development Resources
- MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk
- MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
- Example Servers: https://modelcontextprotocol.io/examples

### Community Resources
- Awesome MCP Servers: https://mcpservers.org/
- MCP Cursor Directory: https://cursor.directory/mcp/
- Glama MCP Servers: https://glama.ai/mcp/servers

---

## Maintenance

### Updating MCP Servers

**Automatic Updates:**
- npx automatically fetches latest versions
- No manual update required for npx-based installations

**Manual Version Pinning:**
```json
"args": [
  "-y",
  "@modelcontextprotocol/server-github@1.2.3"
]
```

### Monitoring

- Check Claude Code logs for MCP server errors
- Verify connectivity periodically
- Review token permissions and expiration dates
- Update documentation when adding new servers

---

## Support and Issues

**MCP-Related Issues:**
- Official MCP GitHub: https://github.com/modelcontextprotocol/modelcontextprotocol/issues
- Claude Code Issues: https://github.com/anthropics/claude-code/issues

**ClaudeTools-Specific Issues:**
- Project GitHub: (Add your Gitea repository URL)
- Contact: (Add support contact)

---

**Installation Date:** 2026-01-17
**Configured By:** Claude Code Agent
**Next Review:** 2026-02-17 (30 days)