npm package: @luismdev/vibecontext
Description: VibeContext MCP Server - Model Context Protocol server for documentation management
Author: Luis M.
Latest version: 1.0.17

# @luismdev/vibecontext

[![npm version](https://badge.fury.io/js/@luismdev%2Fvibecontext.svg)](https://badge.fury.io/js/@luismdev%2Fvibecontext)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

VibeContext MCP Server - A Model Context Protocol server for AI-powered documentation management.

## Features

🔧 **4 Essential Tools:**

- **readDoc**: Read documentation files
- **writeDoc**: Create/edit documentation files
- **listTentatives**: List pending \*.vc.md files
- **readCodeDiff**: Get git diffs for code analysis

🛡️ **Security First:**

- Sandboxed file access (repository only)
- Path traversal protection
- Allowed file extensions validation
- Standard MCP protocol compliance

🚀 **Easy Integration:**

- Works with Cursor IDE
- Compatible with Claude Desktop
- Standard MCP protocol (JSON-RPC 2.0)
- TypeScript support included

## Installation

```bash
npm install -g @luismdev/vibecontext
```

## Quick Start

### 1. Configuration

Create or update your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "vibecontext": {
      "command": "vibecontext-mcp",
      "env": {
        "OPENAI_API_KEY": "your-api-key-optional"
      }
    }
  }
}
```

### 2. Usage

Once configured, the tools are available in your MCP-compatible client:

```javascript
// Read a documentation file
readDoc({ path: 'docs/README.md' });

// Write documentation
writeDoc({
  path: 'docs/feature.md',
  content: '# New Feature\n\nDescription...',
});

// List tentative files
listTentatives();

// Get code diff
readCodeDiff({ filePath: 'src/app.ts' });
```

## Tools Reference

### readDoc(params)

Reads content from documentation files.

**Parameters:**

- `path` (string): Relative path to file

**Returns:** File content as string

### writeDoc(params)

Creates or overwrites documentation files.

**Parameters:**

- `path` (string): Relative path for the file
- `content` (string): File content

**Returns:** Success message

### listTentatives()

Lists all `*.vc.md` files in `.vibecontext/tentative/` directory.

**Returns:** Array of tentative files with metadata

### readCodeDiff(params)

Gets git diff for a specific file against HEAD.

**Parameters:**

- `filePath` (string): Path to file for diff

**Returns:** Git diff output

## Security

- **Sandboxed Access**: Only files within the current repository
- **Allowed Extensions**: `.md`, `.vc.md`, `.txt` only
- **Path Validation**: Prevents directory traversal attacks
- **Standard Protocol**: Uses official MCP specification

## Development

### Local Setup

```bash
# Clone the repository
git clone https://github.com/luisMDev/vibe-context.git
cd vibe-context/packages/mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start
```

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT © Luis M. (@luisMDev)

## Links

- [GitHub Repository](https://github.com/luisMDev/vibe-context)
- [Issues](https://github.com/luisMDev/vibe-context/issues)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## Changelog

### 1.0.0

- Initial release
- Core MCP tools implementation
- Security sandbox
- TypeScript support
- Standard MCP protocol compliance