# 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!**