# Renderer MCP Server

<div align="center">

[![npm version](https://img.shields.io/npm/v/renderer-mcp-server.svg)](https://www.npmjs.com/package/renderer-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Model Context Protocol](https://img.shields.io/badge/MCP-Enabled-blue.svg)](https://modelcontextprotocol.io)

**AI-powered assistant for the [Renderer](https://github.com/NishikantaRay/renderer) portfolio framework**

Helps users explore documentation, validate configurations, generate templates, and customize their portfolios through natural language.

[Features](#-features) • [Installation](#-installation) • [Usage](#-usage) • [Tools](#-available-tools) • [Configuration](#-configuration)

</div>

---

## 🌟 Features

- **📚 Interactive Documentation** - Search and explore Renderer docs with natural language queries
- **✅ Configuration Validation** - Validate TOML configs with detailed error messages
- **🎨 Template Generation** - Generate starter templates customized to your needs
- **💡 Smart Examples** - Get configuration examples with explanations
- **🔍 Feature Discovery** - Search for specific Renderer features and capabilities
- **📖 Setup Guides** - Step-by-step guides for beginners and advanced users
- **🗂️ Repository Browser** - Browse Renderer repository files and directories

## 📦 Installation

### NPM (Recommended)

```bash
npm install -g renderer-mcp-server
```

### From Source

```bash
git clone https://github.com/NishikantaRay/renderer-mcp-server.git
cd renderer-mcp-server
npm install
npm run build
npm link
```

## 🚀 Usage

### With Claude Desktop

1. **Install the server:**
   ```bash
   npm install -g renderer-mcp-server
   ```

2. **Configure Claude Desktop:**
   
   Edit your Claude config file:
   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

   Add the server configuration:
   ```json
   {
     "mcpServers": {
       "renderer": {
         "command": "renderer-mcp",
         "env": {
           "GITHUB_TOKEN": "your_github_token_here"
         }
       }
     }
   }
   ```

3. **Get a GitHub Token (Optional but recommended):**
   - Go to https://github.com/settings/tokens
   - Create a new token with `repo` scope
   - Add it to the config above

4. **Restart Claude Desktop**

### With Other MCP Clients

Any MCP-compatible client can use this server:

```typescript
import { Client } from "@modelcontextprotocol/sdk/client/index.js";

const client = new Client({
  name: "my-client",
  version: "1.0.0",
});

// Connect to the server
await client.connect({
  command: "renderer-mcp",
  env: {
    GITHUB_TOKEN: process.env.GITHUB_TOKEN,
  },
});
```

## 🛠️ Available Tools

### 1. **explore_renderer_docs**
Search and explore Renderer framework documentation.

```
Query: "How do I configure dark mode?"
Returns: Relevant documentation sections
```

### 2. **get_renderer_file**
Get contents of specific files from the Renderer repository.

```
Path: "config/home.toml"
Returns: File contents with syntax highlighting
```

### 3. **list_renderer_files**
List files and directories in the Renderer repository.

```
Path: "config"
Returns: Directory listing with file types
```

### 4. **validate_toml_config**
Validate TOML configuration files.

```
Config Content: "[profile]\nname = 'John'"
Config Type: "home"
Returns: Validation results with suggestions
```

### 5. **generate_starter_template**
Generate customized starter templates.

```
Input: { name: "John Doe", github: "johndoe", include_projects: true }
Returns: Complete project structure and configs
```

### 6. **get_config_example**
Get example configurations with explanations.

```
Config Type: "projects"
Returns: Annotated example configuration
```

### 7. **search_renderer_features**
Search for specific features.

```
Feature: "analytics"
Returns: Feature documentation and examples
```

### 8. **get_setup_guide**
Get setup instructions.

```
Level: "beginner" | "advanced"
Returns: Step-by-step setup guide
```

## 📋 Configuration

### Environment Variables

- **GITHUB_TOKEN** (optional): GitHub personal access token for higher API rate limits
  - Without token: 60 requests/hour
  - With token: 5000 requests/hour
  - Scope required: `public_repo`

### Custom Repository

By default, the server connects to `NishikantaRay/renderer`. To use a fork or different repository:

Edit [src/constants.ts](src/constants.ts):

```typescript
export const DEFAULT_CONFIG: RendererConfig = {
    owner: "your-username",
    repo: "your-repo",
    branch: "main"
};
```

## 📁 Project Structure

```
renderer-mcp-server/
├── src/
│   ├── index.ts           # Main server entry point
│   ├── types.ts           # TypeScript type definitions
│   ├── constants.ts       # Tool definitions and config
│   ├── github.ts          # GitHub API interactions
│   └── tools/             # Tool implementations
│       ├── validator.ts   # TOML validation
│       ├── template.ts    # Template generation
│       ├── examples.ts    # Configuration examples
│       ├── features.ts    # Feature search
│       └── guides.ts      # Setup guides
├── build/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md
```

## 🔧 Development

### Prerequisites

- Node.js 18 or higher
- npm or yarn
- TypeScript 5.3+

### Setup

```bash
# Clone the repository
git clone https://github.com/NishikantaRay/renderer-mcp-server.git
cd renderer-mcp-server

# Install dependencies
npm install

# Build
npm run build

# Watch mode (for development)
npm run watch
```

### Testing

```bash
# Build the project
npm run build

# Test with MCP inspector
npx @modelcontextprotocol/inspector renderer-mcp
```

## 📝 Example Interactions

### Generate a Portfolio

**User:** "Create a portfolio template for John Doe with GitHub and LinkedIn"

**Server:** Generates complete starter template with:
- Customized TOML configurations
- Project structure
- Setup instructions
- Next steps

### Validate Configuration

**User:** "Validate this TOML: [profile]\nname = 'Jane'"

**Server:** 
- ✅ Validates syntax
- Checks for required fields
- Provides suggestions
- Shows parsed structure

### Explore Features

**User:** "How do I add dark mode to my portfolio?"

**Server:** Returns documentation about:
- Theme configuration
- Available options
- Implementation details
- Code examples

## 🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Add tests if applicable
5. Commit: `git commit -m 'Add amazing feature'`
6. Push: `git push origin feature/amazing-feature`
7. Open a Pull Request

### Development Guidelines

- Follow TypeScript best practices
- Keep functions small and focused
- Add JSDoc comments for public APIs
- Update README for new features
- Test thoroughly before submitting

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details

## 🔗 Related Projects

- **[Renderer](https://github.com/NishikantaRay/renderer)** - The portfolio framework this server supports
- **[Model Context Protocol](https://modelcontextprotocol.io)** - The protocol specification
- **[MCP SDK](https://github.com/modelcontextprotocol/sdk)** - Official MCP SDK

## 💬 Support

- **Issues**: [GitHub Issues](https://github.com/NishikantaRay/renderer-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/NishikantaRay/renderer-mcp-server/discussions)
- **Renderer Docs**: [Documentation](https://github.com/NishikantaRay/renderer/tree/main/docs)

## 🙏 Acknowledgments

- Built with [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)
- Powers the [Renderer](https://github.com/NishikantaRay/renderer) framework
- Inspired by the MCP community

---

<div align="center">

**Made with ❤️ by [Nishikanta Ray](https://github.com/NishikantaRay)**

⭐ Star this repo if you find it helpful!

</div>