vaibhavkkk/mcp-server

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

JIRA Integration Tools (Optional)

Available when JIRA is configured with required environment variables

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

# 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)

# 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)
4. JIRA_SUB_COMPONENT (optional): Default component for created tickets

Creating a JIRA API Token:

1. Go to Atlassian Account Settings
2. Click "Create API token"
3. Give it a label (e.g., "GalaxyMCP")
4. Copy the generated token

3. Test the Server

# 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

# 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:

{
  "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

# 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

# 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

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:

---
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:

npm install
npm run build

Personas not loading:

# 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

# 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

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!