npm package: @luismdev/vibecontext-mcp
Description: VibeContext Model Context Protocol (MCP) server for AI agents to interact with project documentation
Author: Luis M
Latest version: 0.0.6

# @vibecontext/mcp-server

[![npm version](https://badge.fury.io/js/@vibecontext%2Fmcp-server.svg)](https://badge.fury.io/js/@vibecontext%2Fmcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A TypeScript Model Context Protocol (MCP) server for AI agents to interact with project documentation. Built with FastMCP framework.

## 🌟 Features

- **Document Management**: Read and write documentation files securely
- **Tentative File Tracking**: List and manage `*.vc.md` files in the `.vibecontext/tentative` directory
- **Git Integration**: Get code diffs against HEAD for any file
- **Security**: Sandboxed file access limited to the workspace directory
- **FastMCP Framework**: Built on the robust FastMCP TypeScript framework
- **CLI Interface**: Easy-to-use command line interface
- **Multiple Transports**: Support for both stdio and HTTP transports

## 📦 Installation

### Global Installation (Recommended)

```bash
npm install -g @vibecontext/mcp-server
```

### Local Installation

```bash
npm install @vibecontext/mcp-server
```

## 🚀 Quick Start

### Command Line Usage

```bash
# Start the server with default settings
vibecontext-mcp start

# Start with custom port and verbose logging
vibecontext-mcp start --port 3000 --verbose

# Use stdio transport (for MCP clients like Claude Desktop)
vibecontext-mcp start --stdio

# Start with custom workspace
vibecontext-mcp start --workspace /path/to/your/project

# Inspect server with FastMCP inspector
vibecontext-mcp inspect
```

### Programmatic Usage

```typescript
import { startMCPServer } from '@vibecontext/mcp-server';

// Start server programmatically
const server = await startMCPServer({
  port: 3333,
  transportType: 'httpStream',
  workspaceRoot: '/path/to/your/project',
  verbose: true,
});
```

## 🔧 Configuration

### Environment Variables

```bash
# Optional: OpenAI API Key for AI functionalities
OPENAI_API_KEY=your_openai_api_key_here

# Optional: Custom server configuration
MCP_SERVER_PORT=3333
MCP_SERVER_HOST=localhost
```

### MCP Client Configuration

#### Claude Desktop

Add to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vibecontext": {
      "command": "vibecontext-mcp",
      "args": ["start", "--stdio", "--verbose"],
      "env": {
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}
```

#### Cursor IDE

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vibecontext-mcp": {
      "command": "vibecontext-mcp",
      "args": ["start", "--stdio"],
      "env": {
        "NODE_ENV": "development"
      }
    }
  }
}
```

#### HTTP/URL Configuration

For HTTP transport, start the server and configure your client:

```json
{
  "mcpServers": {
    "vibecontext-mcp": {
      "url": "http://localhost:3333/mcp"
    }
  }
}
```

## 🛠️ Available Tools

### readDoc

Read the content of a document file.

**Parameters:**

- `path` (string): Relative path to the file within the workspace

### writeDoc

Create or overwrite a document file with provided content.

**Parameters:**

- `path` (string): Relative path to the file within the workspace
- `content` (string): Content to write to the file

### listTentatives

List all tentative `*.vc.md` files in the `.vibecontext/tentative/` directory.

**Parameters:** None

### readCodeDiff

Get the diff of a file against HEAD using git.

**Parameters:**

- `filePath` (string): Relative path to the file within the workspace

## 🔒 Security Features

- **Workspace Sandboxing**: All file operations are restricted to the specified workspace directory
- **Path Validation**: Prevents path traversal attacks through robust path validation
- **File Extension Filtering**: Only allows access to specific file types (`.md`, `.vc.md`, `.txt`, `.json`, `.ts`, `.js`)
- **Error Handling**: Comprehensive error handling with descriptive messages

## 📚 API Reference

### MCPServerConfig

```typescript
interface MCPServerConfig {
  port?: number; // Server port (default: 3333)
  host?: string; // Server host (default: 'localhost')
  transportType?: 'stdio' | 'httpStream'; // Transport type (default: 'httpStream')
  workspaceRoot?: string; // Workspace root path (default: process.cwd())
  verbose?: boolean; // Enable verbose logging (default: false)
}
```

### startMCPServer(config?: MCPServerConfig)

Starts the MCP server with the given configuration.

**Returns:** Promise<FastMCP> - The running FastMCP server instance

## 🧪 Development

### Local Development

```bash
# Clone the repository
git clone https://github.com/your-username/vibe-context.git
cd vibe-context/apps/mcp

# Install dependencies
npm install

# Start in development mode
npm run dev

# Build the package
npm run build

# Test the CLI
npm run cli start --verbose
```

### Testing

```bash
# Run tests
npm test

# Test with FastMCP inspector
npm run cli inspect
```

## 📖 Examples

### Basic Usage with Different Clients

```bash
# For Claude Desktop (stdio)
vibecontext-mcp start --stdio --workspace ~/my-project

# For web-based MCP clients (HTTP)
vibecontext-mcp start --port 3333 --verbose

# For development with inspector
vibecontext-mcp inspect --workspace ~/my-project
```

### Programmatic Integration

```typescript
import { startMCPServer, MCPServerConfig } from '@vibecontext/mcp-server';

async function setupMCPServer() {
  const config: MCPServerConfig = {
    port: 3333,
    transportType: 'httpStream',
    workspaceRoot: '/path/to/project',
    verbose: true,
  };

  const server = await startMCPServer(config);
  console.log('MCP Server is running!');

  return server;
}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'feat: add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request

## 📝 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙋‍♂️ Support

- **Issues**: [GitHub Issues](https://github.com/luisMDev/vibe-context/issues)
- **Documentation**: [MCP Setup Guide](../../docs/MCP_SETUP.md)
- **Community**: Join our discussions

## 🔗 Related Projects

- [FastMCP](https://github.com/punkpeye/fastmcp) - The underlying MCP framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - Official MCP documentation