# Changerawr MCP Server

A Model Context Protocol (MCP) server for Changerawr, enabling AI assistants like Claude to manage changelogs, projects, and content through natural language.

## Features

🚀 **Project Management**
- List, create, update, and delete projects
- Configure project settings (public visibility, auto-publish, approval requirements)

📝 **Changelog Management**
- Create, update, publish, and unpublish changelog entries
- Support for versioning and tagging
- Markdown content with rich formatting

🏷️ **Tag Organization**
- Create and manage tags for organizing entries
- Project-specific tag management

📊 **Analytics & Insights**
- Get dashboard statistics and analytics
- Track project information

🔧 **Project Settings**
- Update project configuration
- Manage default tags and publishing settings

## Installation & Setup

### Prerequisites
- Node.js 18+ installed
- Access to a Changerawr instance
- An admin API key from Changerawr

### 1. Clone the Repository
```bash
git clone <repository-url>
cd changerawr-mcp-server
```

### 2. Install Dependencies
```bash
npm install
```

### 3. Get Your Changerawr API Key
1. Log in to your Changerawr admin panel
2. Navigate to **Settings → API Keys**
3. Create a new API key with admin permissions
4. Copy the key (format: `chr_...`)

### 4. Configure Claude Desktop

Add this configuration to your Claude Desktop `config.json`:

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

```json
{
  "mcpServers": {
    "changerawr": {
      "command": "npx",
      "args": ["tsx", "C:\\Users\\username\\WebstormProjects\\changerawr-mcp-server\\src\\index.ts"],
      "env": {
        "CHANGERAWR_API_KEY": "chr_your_api_key_here",
        "CHANGERAWR_BASE_URL": "https://your-changerawr-domain.com",
        "NODE_ENV": "development"
      }
    }
  }
}
```

**Important:** Replace the path with your actual project location and update the environment variables:
- `CHANGERAWR_API_KEY`: Your actual API key from Changerawr
- `CHANGERAWR_BASE_URL`: Your Changerawr instance URL

### 5. Restart Claude Desktop
Close Claude Desktop completely and restart it for the configuration to take effect.

## Usage Examples

### Project Management
**Create a new project:**
> "Create a new project called 'Mobile App' with auto-publish enabled and make it public"

**List all projects:**
> "Show me all my projects in Changerawr"

**Update project settings:**
> "Make the Mobile App project private and require approval for all changes"

### Changelog Management
**Create a draft changelog entry:**
> "Create a changelog entry for version 2.1.0 titled 'Enhanced Search Features' with details about the new search functionality"

**Create and publish immediately:**
> "Create and immediately publish a changelog entry for version 2.1.1 about bug fixes"

**Publish a draft:**
> "Show me unpublished changelog entries and publish the one about enhanced security"

**Update an existing entry:**
> "Update the changelog entry with ID xyz to include information about performance improvements"

### Tag Management
**List tags for a project:**
> "Show me all tags available for the Mobile App project"

**Create a new tag:**
> "Create a new tag called 'Security Update' for the Mobile App project"

### Analytics
**Get dashboard statistics:**
> "Show me the dashboard statistics and recent activity"

## Available Tools

The MCP server provides **22 tools** for comprehensive Changerawr management:

### Project Tools (5)
- `list_projects` - List all projects
- `get_project` - Get project details
- `create_project` - Create new project
- `update_project` - Update project settings
- `delete_project` - Delete project (admin)

### Changelog Tools (8)
- `list_changelog_entries` - List changelog entries with filtering
- `get_changelog_entry` - Get specific entry details
- `create_changelog_entry` - Create new draft entry
- `update_changelog_entry` - Update existing entry
- `publish_changelog_entry` - Publish entry to make it public
- `unpublish_changelog_entry` - Hide entry from public
- `delete_changelog_entry` - Delete entry permanently (admin)
- `create_and_publish_changelog_entry` - Create and publish in one step

### Tag Tools (3)
- `list_tags` - List tags for a project
- `create_tag` - Create new project tag
- `delete_tag` - Delete tag (limited API support)

### Settings Tools (2)
- `get_project_settings` - Get project configuration
- `update_project_settings` - Update project settings

### Analytics Tools (1)
- `get_dashboard_stats` - Get dashboard statistics

### Resources (3)
- `changerawr://projects` - List of all projects
- `changerawr://projects/{projectId}/changelog` - Project changelog entries
- `changerawr://tags` - Available tags

## Workflows

### Draft → Review → Publish (Recommended)
1. **Create Draft**: `create_changelog_entry` - Creates unpublished entry
2. **Review Content**: Edit and review the content
3. **Publish**: `publish_changelog_entry` - Makes it visible to users

### Immediate Publishing
1. **Create & Publish**: `create_and_publish_changelog_entry` - One-step process

## Admin Permissions

All API keys have admin access, enabling:
- ✅ **Instant project creation/deletion**
- ✅ **Immediate publish/unpublish**
- ✅ **Direct entry deletion**
- ✅ **Full project settings control**
- ✅ **Tag management**

## Troubleshooting

### Connection Issues
1. **Verify API key**: Ensure it starts with `chr_` and has admin permissions
2. **Check URL**: Verify your Changerawr instance URL is correct
3. **Test connection**: Try accessing your Changerawr instance in a browser

### Claude Desktop Issues
1. **Check logs**: Windows: `%APPDATA%\Claude\logs\`
2. **Restart completely**: Close Claude Desktop from system tray
3. **Verify config path**: Ensure the file path in config.json is correct

### Tool Failures
1. **Check stderr output**: The MCP server logs detailed error information
2. **Verify project IDs**: Ensure you're using correct project/entry IDs
3. **API permissions**: Confirm your API key has admin access

## Development

### Run in Development Mode
```bash
cd changerawr-mcp-server
npx tsx src/index.ts
```

### Testing Tools
Use the MCP Inspector for testing:
```bash
npx @modelcontextprotocol/inspector npx tsx src/index.ts
```

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `CHANGERAWR_API_KEY` | ✅ | Your Changerawr API key (starts with `chr_`) |
| `CHANGERAWR_BASE_URL` | ✅ | Your Changerawr instance URL |
| `NODE_ENV` | ❌ | Set to `development` for detailed logging |

## Architecture

```
src/
├── index.ts              # Main MCP server entry point
├── client/
│   └── changerawr-client.ts  # API client with Zod validation
├── tools/                # MCP tools for AI interactions
│   ├── index.ts          # Tool registry
│   ├── project-tools.ts  # Project management (5 tools)
│   ├── changelog-tools.ts # Changelog operations (8 tools)
│   ├── tag-tools.ts      # Tag management (3 tools)
│   ├── settings-tools.ts # Project settings (2 tools)
│   └── analytics-tools.ts # Dashboard analytics (1 tool)
├── resources/            # MCP resources for data access
│   ├── index.ts          # Resource registry
│   ├── project-resources.ts
│   └── changelog-resources.ts
└── utils/
    └── validation.ts     # Input validation utilities
```

## Security

- Uses Changerawr's existing API key authentication
- Respects admin permissions and role-based access
- All operations logged via Changerawr's audit system
- Input validation and error handling for safe operations

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Check the troubleshooting section above
- Review Claude Desktop logs for detailed error information
- Ensure your Changerawr instance is accessible and API key is valid