README.mdā¢8.04 kB
# 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