@vibecontext/mcp-server

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)

npm install -g @vibecontext/mcp-server

Local Installation

npm install @vibecontext/mcp-server

🚀 Quick Start

Command Line Usage

# 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

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

# 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):

{
  "mcpServers": {
    "vibecontext": {
      "command": "vibecontext-mcp",
      "args": ["start", "--stdio", "--verbose"],
      "env": {
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}

Cursor IDE

Add to your .cursor/mcp.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:

{
  "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

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 - The running FastMCP server instance

🧪 Development

Local Development

# 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

# Run tests
npm test

# Test with FastMCP inspector
npm run cli inspect

📖 Examples

Basic Usage with Different Clients

# 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

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 file for details.

🙋‍♂️ Support

• Issues: GitHub Issues
• Documentation: MCP Setup Guide
• Community: Join our discussions

🔗 Related Projects

• FastMCP - The underlying MCP framework
• Model Context Protocol - Official MCP documentation