GalaxyMCP Server
by vaibhavkkk
README.md
# GalaxyMCP Server
š A Model Context Protocol (MCP) server for AI persona management with Galaxy theme. Built with TypeScript and designed for seamless integration with AI assistants like Claude and Augment AI.
## Features
- š **Persona Management**: Activate different AI personalities for specialized tasks
- š ļø **6 MCP Tools**: Complete persona lifecycle management
- š« **JIRA Integration**: Full JIRA API support with 8 additional tools for ticket management
- š **Markdown-Based Personas**: Easy-to-edit persona definitions with YAML frontmatter
- š§ **TypeScript**: Type-safe development with modern ES modules
- š **Galaxy Theme**: Space-themed indicators and branding
- š **Simplified Architecture**: Streamlined codebase for easy understanding and extension
- š¦ **Self-Contained**: All persona logic in a single main file for clarity
## Available Tools
### Persona Management Tools
| Tool | Description |
|------|-------------|
| `list_personas` | List all available personas with details |
| `activate_persona` | Activate a specific persona by name or filename |
| `get_active_persona` | Get currently active persona information |
| `deactivate_persona` | Return to default mode |
| `get_persona_details` | View detailed persona information and content |
| `reload_personas` | Refresh personas from filesystem |
### JIRA Integration Tools (Optional)
*Available when JIRA is configured with required environment variables*
| Tool | Description |
|------|-------------|
| `get_jira_ticket` | Retrieve JIRA ticket information by ticket key |
| `create_jira_ticket` | Create a new JIRA ticket (story) with workspace intelligence |
| `create_jira_epic` | Create a new JIRA epic for organizing multiple related stories |
| `update_jira_ticket` | Update an existing JIRA ticket with new information |
| `add_jira_comment` | Add a comment to an existing JIRA ticket |
| `link_jira_story_to_parent` | Link a JIRA story to its parent ticket |
| `link_jira_epic_to_parent` | Link a JIRA epic to its parent ticket |
| `attach_file_to_jira` | Attach a file to an existing JIRA ticket |
## Built-in Personas
- **Technical Analyst** - Systematic problem-solver for deep technical analysis and architectural decisions
## Prerequisites
- **Node.js**: v20.0.0 or higher
- **npm**: v10.0.0 or higher
- **TypeScript**: v5.0.0 or higher
## Quick Start
### 1. Installation
```bash
# Navigate to the project directory
cd /Users/vkakkar/Documents/self/Projects/AI_MCP/galaxymcp-server
# Install dependencies
npm install
# Build the TypeScript code
npm run build
```
### 2. Environment Setup (Optional)
```bash
# Set user identity for persona attribution
export GALAXY_USER="your-username"
# Custom personas directory (optional)
export GALAXY_PERSONAS_DIR="/path/to/custom/personas"
# JIRA Integration (optional)
export JIRA_BASE_URL="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_TOKEN="your-jira-api-token"
export JIRA_SUB_COMPONENT="Galaxy-Core"
```
#### JIRA Configuration
To enable JIRA integration, you need to set up the following environment variables:
1. **JIRA_BASE_URL**: Your JIRA instance URL (e.g., `https://company.atlassian.net`)
2. **JIRA_EMAIL**: Your JIRA account email
3. **JIRA_TOKEN**: Your JIRA API token ([How to create](https://support.atlassian.com/atlassian-account/docs/manage-api-tokens-for-your-atlassian-account/))
4. **JIRA_SUB_COMPONENT** (optional): Default component for created tickets
**Creating a JIRA API Token:**
1. Go to [Atlassian Account Settings](https://id.atlassian.com/manage-profile/security/api-tokens)
2. Click "Create API token"
3. Give it a label (e.g., "GalaxyMCP")
4. Copy the generated token
### 3. Test the Server
```bash
# Start the server
npm start
# Or with environment variables
GALAXY_USER="vaibhavkkk" npm start
```
**Expected Output:**
```
GalaxyMCP server running on stdio
Loaded persona: Technical Analyst (technical-analyst_20250714-130000_galaxymcp)
```
## Integration with Augment AI
### Step 1: Get Absolute Path
```bash
# Get the absolute path to your GalaxyMCP installation
cd /Users/vkakkar/Documents/self/Projects/AI_MCP/galaxymcp-server
pwd
# Copy this path: /Users/vkakkar/Documents/self/Projects/AI_MCP/galaxymcp-server
```
### Step 2: Configure MCP Server in Augment AI
1. Open IntelliJ IDEA
2. Go to **Preferences** (ā + ,)
3. Navigate to **Tools** ā **Augment AI** ā **MCP Servers** (or similar)
4. Add new MCP server with these settings:
**Configuration:**
```json
{
"mcpServers": {
"galaxymcp": {
"command": "node",
"args": ["/Users/vkakkar/Documents/self/Projects/AI_MCP/galaxymcp-server/dist/index.js"],
"env": {
"GALAXY_USER": "vaibhavkkk",
"JIRA_BASE_URL": "https://your-company.atlassian.net",
"JIRA_EMAIL": "your-email@company.com",
"JIRA_TOKEN": "your-jira-api-token",
"JIRA_SUB_COMPONENT": "Galaxy-Core"
}
}
}
}
```
**Note:** JIRA environment variables are optional. If not provided, only persona management tools will be available.
### Step 3: Restart and Test
1. Restart IntelliJ IDEA completely
2. Open Augment AI panel
3. Look for GalaxyMCP tools in available tools
4. Test with: `list_personas`
## Usage Examples
### Basic Persona Management
```bash
# List all available personas
list_personas
# Activate the Technical Analyst persona
activate_persona "Technical Analyst"
# Get details about current persona
get_active_persona
# View full persona details
get_persona_details "Technical Analyst"
# Deactivate persona
deactivate_persona
```
### Working with Technical Analyst
Once activated, the Technical Analyst persona will:
- Provide systematic technical analysis
- Focus on architectural decisions
- Consider scalability and performance
- Offer detailed debugging approaches
- Suggest concrete implementation steps
### JIRA Integration Examples
*Available when JIRA is configured*
```bash
# Get ticket information
get_jira_ticket "ENG-12345"
# Create a new story
create_jira_ticket {
"summary": "Implement user authentication",
"description": "Add JWT-based authentication to the API",
"issue_type": "Story",
"labels": ["backend", "security"]
}
# Create an epic
create_jira_epic {
"summary": "User Management System",
"description": "Complete user management functionality",
"labels": ["epic", "user-management"]
}
# Add a comment
add_jira_comment {
"ticket_key": "ENG-12345",
"comment_text": "Implementation completed and ready for review"
}
# Link a story to an epic
link_jira_story_to_parent {
"story_key": "ENG-12346",
"parent_key": "ENG-12345",
"link_type": "Blocks"
}
```
## Project Structure
```
galaxymcp-server/
āāā src/
ā āāā index.ts # Main MCP server with all logic
ā āāā types/
ā ā āāā persona.ts # Persona type definitions
ā ā āāā mcp.ts # MCP-related types
ā ā āāā index.ts # Type exports
ā āāā persona/
ā ā āāā PersonaManager.ts # Persona loading and management (unused in current impl)
ā āāā utils/
ā āāā filesystem.ts # Utility functions (unused in current impl)
āāā personas/
ā āāā technical-analyst.md # Technical Analyst persona
āāā dist/ # Compiled JavaScript (auto-generated)
āāā package.json # Project configuration
āāā tsconfig.json # TypeScript configuration
āāā README.md # This file
āāā LICENSE # MIT License
āāā .gitignore # Git ignore rules
```
**Note**: The current implementation uses a simplified architecture where all logic is contained in `src/index.ts` for clarity and ease of understanding.
## Development
### Available Scripts
```bash
npm run build # Compile TypeScript
npm run start # Run the server
npm run dev # Watch mode for development
npm run clean # Remove compiled files
npm run rebuild # Clean and rebuild
npm run setup # Install deps and build
```
### Adding New Personas
1. Create a new `.md` file in the `personas/` directory
2. Follow the YAML frontmatter format:
```markdown
---
name: "Your Persona Name"
description: "Brief description"
triggers: ["keyword1", "keyword2"]
version: "1.0"
author: "your-username"
category: "professional"
unique_id: "your-persona_20250714-130000_your-username"
---
# Your Persona Name
Your persona instructions go here...
```
3. Reload personas: `reload_personas`
## Troubleshooting
### Common Issues
**"Cannot find module" errors:**
```bash
npm install
npm run build
```
**Personas not loading:**
```bash
# Check personas directory exists
ls -la personas/
# Reload personas
reload_personas
```
**Augment AI doesn't see tools:**
- Restart IntelliJ completely
- Verify absolute paths in MCP configuration
- Check Augment AI plugin version supports MCP
### Debug Mode
```bash
# Run with debug output
DEBUG=galaxymcp:* npm start
# Check server compilation
node --version # Should be v20+
npm run build # Should complete without errors
```
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `GALAXY_USER` | User identity for persona attribution | `null` |
| `GALAXY_PERSONAS_DIR` | Custom personas directory | `./personas` |
## Architecture Notes
This implementation uses a **simplified architecture** compared to DollhouseMCP:
- **Single File Logic**: All MCP server logic is in `src/index.ts`
- **Inline Persona Management**: Persona loading and management is built into the main server class
- **Direct Tool Handling**: Tools are handled directly in the main server without separate tool registry
- **Simplified Types**: Minimal type definitions for clarity
This approach makes the codebase easier to understand and modify while maintaining full MCP compatibility.
## License
MIT License - see LICENSE file for details.
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request
---
š **Transform your AI interactions with the power of Galaxy personas!**
TDQS
A3.7/5.0
Scored across 6 tools
Disambiguation5/5
Each tool has a distinct purpose: activate, deactivate, get active, get details, list, and reload personas. No overlap or ambiguity.
Naming Consistency5/5
All tool names follow a consistent verb_noun pattern in snake_case (e.g., activate_persona, list_personas), ensuring predictability.
Tool Count5/5
With 6 tools focused on persona management, the set is well-scoped and neither too sparse nor excessive for the domain.
Completeness4/5
The tools cover core persona lifecycle operations (activate, deactivate, list, details) and include reload, but lack explicit create or delete functions, which may be handled externally.
Maintenance
ActivityInactive
ResponsivenessNo recent community issues