Changerawr MCP Server

# 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