# Clarity PPM MCP Server

A Model Context Protocol (MCP) server for CA Clarity PPM that enables AI assistants to interact with your Clarity PPM system through a standardized interface.

## Features

### 🔍 Discovery Tools
- **clarity_list_objects** - Discover all available object types (standard and custom)
- **clarity_describe_object** - Get detailed metadata about any object
- **clarity_get_lookup_values** - Retrieve dropdown/lookup values
- **clarity_search_metadata** - Search objects and fields by name (supports Hebrew!)

### 📋 CRUD Operations
- **clarity_list_records** - List records with smart filtering and pagination
- **clarity_get_record** - Get a single record with all details
- **clarity_count_records** - Count records matching criteria
- **clarity_get_children** - Get child records (e.g., tasks under a project)
- **clarity_create_record** - Create new records
- **clarity_update_record** - Update existing records
- **clarity_delete_record** - Delete records

### 📊 Analytics
- **clarity_get_distribution** - Get distribution data for visualizations

### 🔗 Deep Linking
- All records include direct links to open in Clarity UI
- Supports projects, tasks, resources, ideas, and custom objects

## Quick Start

### 1. Install Dependencies

```bash
npm install
```

### 2. Configure Environment

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

Edit `.env`:
```
CLARITY_BASE_URL=https://your-clarity.com
CLARITY_USERNAME=your_username
CLARITY_PASSWORD=your_password
```

### 3. Build

```bash
npm run build
```

### 4. Run

**stdio mode (for Claude Desktop, etc.):**
```bash
npm start
```

**HTTP mode (for web integrations):**
```bash
TRANSPORT=http npm start
```

## Configuration for Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "clarity-ppm": {
      "command": "node",
      "args": ["/path/to/clarity-ppm-mcp-server/dist/index.js"],
      "env": {
        "CLARITY_BASE_URL": "https://your-clarity.com",
        "CLARITY_USERNAME": "your_username",
        "CLARITY_PASSWORD": "your_password"
      }
    }
  }
}
```

## Example Usage

Once connected, you can ask Claude:

- "What objects are available in Clarity?"
- "Show me all active projects"
- "How many tasks are in project 5001?"
- "Create a new task called 'Review Requirements' under project 5001"
- "What's the status distribution of all projects?"
- "Show me custom objects"
- "Find fields related to budget"

## Architecture

```
┌─────────────────────────────────────────────────────────┐
│                    MCP Client                           │
│              (Claude, VS Code, etc.)                    │
└─────────────────────────────────────────────────────────┘
                          │
                          │ MCP Protocol
                          ▼
┌─────────────────────────────────────────────────────────┐
│              Clarity PPM MCP Server                     │
├─────────────────────────────────────────────────────────┤
│  Tools        │  Resources     │  Services              │
│  ─────────    │  ──────────    │  ────────              │
│  - Discovery  │  - Metadata    │  - ClarityApiClient    │
│  - Records    │  - Context     │  - MetadataService     │
│  - Analytics  │  - Links       │  - LookupService       │
│  - Workflow   │                │  - LinkGenerator       │
└─────────────────────────────────────────────────────────┘
                          │
                          │ REST API
                          ▼
┌─────────────────────────────────────────────────────────┐
│                 CA Clarity PPM                          │
│        (SaaS / On-Premise / Hybrid)                     │
└─────────────────────────────────────────────────────────┘
```

## Supported Clarity Versions

- Clarity PPM 15.x and above
- Works with SaaS, On-Premise, and Hybrid deployments

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run in development (with auto-reload)
npm run dev

# Run tests
npm test
```

## License

MIT

## Contributing

Contributions welcome! Please read the contributing guidelines first.