# BIP Monitor MCP Server

A Model Context Protocol (MCP) server for monitoring Next.js development servers with intelligent error categorization, smart diagnostics, and performance tracking.

## Features

- **🔍 Intelligent Error Categorization**: Automatically categorizes errors into syntax, runtime, build, dependency, and port issues
- **💡 Smart Fix Suggestions**: Provides actionable fix suggestions for each error category
- **📊 Performance Tracking**: Monitors compile times and build performance metrics
- **💾 Persistent Logging**: Errors persist across sessions in `~/.bip-monitor/`
- **🔄 Real-time Monitoring**: Live dev server monitoring with stdout/stderr capture
- **📡 MCP Resources**: Access errors and status through standardized MCP resources
- **🛠️ MCP Tools**: Control dev server and query errors programmatically

## Installation

### For Claude Code CLI

If your project has a `.mcp.json` file, add the server configuration:

```json
{
  "mcpServers": {
    "bip-monitor": {
      "command": "npx",
      "args": ["-y", "bip-monitor-mcp"]
    }
  }
}
```

Or install locally in your project:

```bash
npm install bip-monitor-mcp
```

Then configure in `.mcp.json`:

```json
{
  "mcpServers": {
    "bip-monitor": {
      "command": "node",
      "args": ["node_modules/bip-monitor-mcp/index.js"]
    }
  }
}
```

### For Claude Desktop

Add to your Claude Desktop configuration:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "bip-monitor": {
      "command": "npx",
      "args": ["-y", "bip-monitor-mcp"]
    }
  }
}
```

Restart Claude Desktop to load the server.

## MCP Resources

The server exposes the following resources:

### `bip://errors/recent`
Returns the last 50 errors with categorization and summary statistics.

```json
{
  "count": 10,
  "errors": [...],
  "summary": {
    "syntax": 3,
    "runtime": 2,
    "build": 1,
    "dependency": 0,
    "port": 0
  }
}
```

### `bip://app/status`
Returns current dev server status including uptime and error count.

```json
{
  "status": "running",
  "pid": 12345,
  "startTime": 1699564800000,
  "errorCount": 10,
  "lastError": {...},
  "uptime": 300000
}
```

### `bip://logs/full`
Returns last 100 lines from stdout/stderr logs. For more control, use the `get_logs` tool.

### `bip://performance/metrics`
Returns performance metrics including compile times.

```json
{
  "lastCompileTime": 142,
  "avgCompileTime": 156,
  "compileTimes": [150, 142, 160, ...]
}
```

## MCP Tools

### `start_dev_server`
Start and monitor the Next.js dev server.

**Parameters:**
- `cwd` (string, required): Working directory for the app

**Example:**
```typescript
{
  "name": "start_dev_server",
  "arguments": {
    "cwd": "/path/to/your/nextjs/app"
  }
}
```

### `get_errors`
Get recent errors with optional filtering.

**Parameters:**
- `limit` (number, default: 10): Number of errors to return
- `category` (string, default: "all"): Filter by category (syntax|runtime|build|dependency|port|all)

### `get_status`
Get current dev server status.

### `clear_errors`
Clear the error log.

### `stop_dev_server`
Stop the running dev server.

### `get_logs`
Get application logs with flexible options.

**Parameters:**
- `lines` (number, default: 100, max: 2000): Number of lines to return from end of log
- `filter` (string, optional): Only return lines containing this text (case-insensitive)

**Examples:**
```
"Get the last 500 lines of logs"
"Get logs filtered by 'error' keyword"
"Get 1000 lines containing 'compile'"
```

## Error Categories

| Category | Triggers | Suggestion |
|----------|----------|------------|
| **port** | `EADDRINUSE`, port already in use | `lsof -ti:3000 \| xargs kill -9` |
| **syntax** | TypeScript/JSX syntax errors | Points to exact file:line |
| **dependency** | Module not found errors | `pnpm install` or `npm install` |
| **build** | Next.js build failures | `rm -rf .next && pnpm dev` |
| **runtime** | Runtime exceptions | Check stack trace |

## Log Files

All logs are stored in `~/.bip-monitor/`:

- **errors.jsonl**: Last 100 errors in JSON Lines format
- **app.log**: Complete stdout/stderr from dev server (access via `get_logs` tool)
- **performance.json**: Compile time metrics and performance data

**Note:** Use the `get_logs` tool to retrieve logs with custom line limits (up to 2000 lines) and optional text filtering.

## Usage Examples

### With Claude Code CLI

```
Read bip://errors/recent
```

### With Claude API

```typescript
const resource = await client.readResource('bip://errors/recent');
console.log(resource.contents[0].text);
```

### Querying Errors

```
Use get_errors tool with limit=5 and category="syntax"
```

### Starting Dev Server

```
Use start_dev_server with cwd="/Users/you/dev/my-nextjs-app"
```

### Getting Logs

```
Use get_logs with lines=500
Use get_logs with lines=1000 and filter="error"
Use get_logs with filter="compile"
```

## Development

### Building from Source

```bash
git clone https://github.com/The-Bip-App/bip-monitor-mcp.git
cd bip-monitor-mcp
npm install
```

### Running Locally

```bash
node index.js
```

The server communicates via stdio using the MCP protocol.

## Requirements

- Node.js >= 18.0.0
- Next.js project with `pnpm dev` or `npm dev` script

## License

MIT

## Contributing

Contributions welcome! Please open an issue or PR.

## Support

For issues, questions, or feature requests, please open an issue on GitHub.