# Principal Architect Service

A comprehensive Model Context Protocol (MCP) server for managing product initiatives, technical requirements, architecture decisions, and related documentation through AI development tools.

## 🎯 Overview

This unified MCP server provides **42+ tools across 8 domains** to help software architects and product teams:

1. **Architecture Decision Records (ADRs)** - Document and track architectural decisions with options, outcomes, and Confluence sync
2. **Technical Requirements** - Create and manage feature requirements with Confluence publishing
3. **Product Requirements** - Define product specifications and requirements
4. **Business Rule Documents** - Document business rules and logic
5. **Technical Estimates** - Track effort estimates and capacity planning
6. **Initiative Resources** - Manage product initiatives and features
7. **Initiative Releases** - Plan and track release schedules
8. **Technology Selections** - Document technology choices and standards

## 🚀 Quick Start

### Prerequisites

- **Node.js 18+** (required)
- **NX Monorepo** tools installed
- **API Server Running** at `http://localhost:3000/api`

### Build the MCP Server

```bash
# Clone and enter the repository
cd principal-architect-service

# Install dependencies
npm install

# Build the MCP server
npx nx build product-initiatives-mcp
```

### Start the API Server

The MCP server requires the API backend to be running:

```bash
# Start the API server (default: http://localhost:3000)
npx nx serve product-initiatives-api
```

---

## 📱 Installation by Tool

### 🖥️ Claude Desktop

Claude Desktop runs the MCP server as a subprocess and communicates via stdio.

#### Configuration Steps

1. **Locate your Claude Desktop config file:**

   - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
   - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
   - **Linux**: `~/.config/Claude/claude_desktop_config.json`

2. **Add the MCP server configuration:**

```json
{
  "mcpServers": {
    "principal-architect": {
      "command": "node",
      "args": [
        "/absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js"
      ],
      "env": {
        "API_URL": "http://localhost:3000/api",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

**Important:** Replace `/absolute/path/to/` with your actual project path.

3. **Alternative: Use npx (if in project directory)**

```json
{
  "mcpServers": {
    "principal-architect": {
      "command": "npx",
      "args": ["nx", "serve", "product-initiatives-mcp"],
      "cwd": "/absolute/path/to/principal-architect-service",
      "env": {
        "API_URL": "http://localhost:3000/api",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

4. **Restart Claude Desktop** completely (quit and relaunch)

5. **Verify Installation:**
   - Open Claude Desktop
   - Look for the 🔌 icon in the chat interface
   - You should see "principal-architect" listed with ~42 tools
   - Try asking: _"List all architecture decision records"_

#### Troubleshooting Claude Desktop

**Server won't start:**

```bash
# Check the build output exists
ls -la dist/product-initiatives-mcp/main.js

# Test the server manually
node dist/product-initiatives-mcp/main.js
```

**Tools not appearing:**

- Open Claude Desktop Developer Tools (Help → Developer Tools)
- Check Console tab for MCP errors
- Verify API server is running: `curl http://localhost:3000/api/health`

---

### 💻 Claude Code (CLI)

Claude Code can use MCP servers via stdio transport. Configuration is stored in `~/.claude/config.yaml`.

#### Configuration Steps

1. **Create or edit your Claude Code config:**

```bash
# Create config directory if needed
mkdir -p ~/.claude

# Edit the config file
nano ~/.claude/config.yaml
```

2. **Add MCP server configuration:**

```yaml
mcpServers:
  principal-architect:
    command: node
    args:
      - /absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js
    env:
      API_URL: http://localhost:3000/api
      LOG_LEVEL: info
```

**Important:** Replace `/absolute/path/to/` with your actual project path.

3. **Alternative: Run from project directory**

```yaml
mcpServers:
  principal-architect:
    command: npx
    args:
      - nx
      - serve
      - product-initiatives-mcp
    cwd: /absolute/path/to/principal-architect-service
    env:
      API_URL: http://localhost:3000/api
      LOG_LEVEL: info
```

4. **Restart Claude Code:**

```bash
# If running in a session, exit and restart
# Or start a new session
claude-code
```

5. **Verify Installation:**

```bash
# In Claude Code, ask:
"What MCP servers are available?"

# Test a tool:
"List all ADRs"
```

#### Using in Claude Code Session

Once configured, you can use natural language to interact with tools:

```
You: "Create a new ADR for choosing between REST and GraphQL APIs"
Claude: [Uses create_architecture_decision_records tool]

You: "Show me all ADRs related to authentication"
Claude: [Uses search_architecture_decision_records tool]

You: "Update ADR-001 to mark the REST option as selected"
Claude: [Uses update_architecture_decision_records tool]
```

#### Troubleshooting Claude Code

**Check MCP server status:**

```bash
# View available MCP servers
cat ~/.claude/config.yaml

# Test server manually
node dist/product-initiatives-mcp/main.js
```

**Debug mode:**
Set `LOG_LEVEL: debug` in your config to see detailed logs.

---

### 🌊 Windsurf

Windsurf supports MCP servers similar to Claude Desktop, with configuration stored in the application settings.

#### Configuration Steps

1. **Locate Windsurf MCP config:**

   - **macOS**: `~/Library/Application Support/Windsurf/User/globalStorage/windsurf.json`
   - **Windows**: `%APPDATA%\Windsurf\User\globalStorage\windsurf.json`
   - **Linux**: `~/.config/Windsurf/User/globalStorage/windsurf.json`

   _Note: Exact path may vary by Windsurf version. Check Settings → MCP Servers for the config location._

2. **Add MCP server configuration:**

```json
{
  "mcpServers": {
    "principal-architect": {
      "command": "node",
      "args": [
        "/absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js"
      ],
      "env": {
        "API_URL": "http://localhost:3000/api",
        "LOG_LEVEL": "info"
      }
    }
  }
}
```

**Important:** Replace `/absolute/path/to/` with your actual project path.

3. **Alternative: Via Windsurf UI**

   Some Windsurf versions support UI-based MCP configuration:

   - Open Settings → Extensions → MCP Servers
   - Click "Add MCP Server"
   - Fill in:
     - **Name**: `principal-architect`
     - **Command**: `node`
     - **Args**: `/absolute/path/to/principal-architect-service/dist/product-initiatives-mcp/main.js`
     - **Environment Variables**:
       - `API_URL=http://localhost:3000/api`
       - `LOG_LEVEL=info`

4. **Reload Windsurf:**

   - Restart Windsurf completely
   - Or use Command Palette: "Reload Window"

5. **Verify Installation:**
   - Open the AI chat panel
   - Look for MCP servers indicator
   - Try: _"What tools are available from the principal-architect server?"_

#### Using in Windsurf

Windsurf integrates MCP tools into the AI coding assistant:

```
You: "Create an ADR for our database selection"
Windsurf: [Uses create_architecture_decision_records]

You: "Show me the ADR we created yesterday"
Windsurf: [Uses list_architecture_decision_records with filters]
```

#### Troubleshooting Windsurf

**Server not loading:**

- Check Windsurf's Output panel → MCP Servers
- Verify the path to main.js is correct and absolute
- Ensure API server is running

**Permission issues:**

```bash
# Make sure the main.js file is executable
chmod +x dist/product-initiatives-mcp/main.js
```

---

## 🛠️ Available Tools

### Architecture Decision Records (ADRs)

**8 tools for documenting architectural decisions:**

| Tool                                         | Description                                                 |
| -------------------------------------------- | ----------------------------------------------------------- |
| `create_architecture_decision_records`       | Create a new ADR with title, problem statement, and options |
| `list_architecture_decision_records`         | List all ADRs (supports pagination and filtering)           |
| `get_architecture_decision_records`          | Get detailed ADR by ID including all options and outcomes   |
| `update_architecture_decision_records`       | Update ADR metadata, problem statement, or decision outcome |
| `update_architecture_decision_record_option` | Update specific option details, diagrams, or code examples  |
| `search_architecture_decision_records`       | Search ADRs by keyword with relevance scoring               |
| `delete_architecture_decision_records`       | Delete an ADR (soft delete preserves history)               |
| `publish_architecture_decision_record`       | Publish ADR to Confluence with ADF formatting               |

### Technical Requirements

**5 tools for feature requirements:**

| Tool                                           | Description                            |
| ---------------------------------------------- | -------------------------------------- |
| `create_technical_requirements`                | Create technical requirements document |
| `list_technical_requirements`                  | List all technical requirements        |
| `get_technical_requirements`                   | Get technical requirements by ID       |
| `update_technical_requirements`                | Update technical requirements          |
| `publish_technical_requirements_to_confluence` | Publish to Confluence                  |

### Product Requirements

**5 tools for product specs:**

| Tool                           | Description                          |
| ------------------------------ | ------------------------------------ |
| `create_product_requirements`  | Create product requirements document |
| `list_product_requirements`    | List all product requirements        |
| `get_product_requirements`     | Get product requirements by ID       |
| `update_product_requirements`  | Update product requirements          |
| `publish_product_requirements` | Publish to Confluence                |

### Business Rule Documents

**4 tools for business logic:**

| Tool                            | Description                      |
| ------------------------------- | -------------------------------- |
| `create_business_rule_document` | Create business rule document    |
| `list_business_rule_documents`  | List all business rule documents |
| `get_business_rule_document`    | Get business rule by ID          |
| `update_business_rule_document` | Update business rule             |

### Technical Estimates

**4 tools for effort estimation:**

| Tool                         | Description                          |
| ---------------------------- | ------------------------------------ |
| `create_technical_estimates` | Create technical estimation document |
| `list_technical_estimates`   | List all technical estimates         |
| `get_technical_estimates`    | Get technical estimate by ID         |
| `update_technical_estimates` | Update technical estimates           |

### Initiative Resources

**4 tools for managing initiatives:**

| Tool                        | Description               |
| --------------------------- | ------------------------- |
| `create_product_initiative` | Create product initiative |
| `list_product_initiatives`  | List all initiatives      |
| `get_product_initiative`    | Get initiative by ID      |
| `update_product_initiative` | Update initiative         |

### Initiative Releases

**5 tools for release planning:**

| Tool                          | Description                   |
| ----------------------------- | ----------------------------- |
| `create_initiative_releases`  | Create initiative release     |
| `list_initiative_releases`    | List all releases             |
| `get_initiative_releases`     | Get release by ID             |
| `update_initiative_releases`  | Update release                |
| `publish_initiative_releases` | Publish release to Confluence |

### Technology Selections

**8 tools for technology decisions:**

| Tool                                       | Description                     |
| ------------------------------------------ | ------------------------------- |
| `create_technology_selection`              | Document a technology selection |
| `list_technology_selections`               | List all technology selections  |
| `get_technology_selection`                 | Get technology selection by ID  |
| `update_technology_selection`              | Update technology selection     |
| `delete_technology_selection`              | Delete technology selection     |
| `search_technology_selections`             | Search technology selections    |
| `filter_technology_selections_by_category` | Filter by category              |
| `deprecate_technology_selection`           | Mark technology as deprecated   |

---

## 💡 Usage Examples

### Example 1: Creating an ADR (Any Tool)

```
You: Create an ADR for choosing between MongoDB and PostgreSQL for our user database

AI: I'll create an Architecture Decision Record for the database selection...
[Uses create_architecture_decision_records tool]

Result: Created ADR-001 with:
- Title: "Database Selection for User Management"
- Problem: Need to choose a database for user data storage
- Options: MongoDB (document), PostgreSQL (relational)
- Status: Proposed
```

### Example 2: Searching ADRs (Claude Desktop)

```
You: Find all ADRs related to authentication

Claude: [Uses search_architecture_decision_records tool with keyword="authentication"]

Found 3 ADRs:
1. ADR-005: OAuth vs JWT Authentication
2. ADR-012: Multi-Factor Authentication Implementation
3. ADR-018: Session Management Strategy
```

### Example 3: Publishing to Confluence (Claude Code)

```bash
claude-code

You: Publish ADR-001 to Confluence

Claude: I'll publish the ADR to Confluence with proper formatting...
[Uses publish_architecture_decision_record tool]

✅ Published to Confluence:
- Page ID: 123456
- URL: https://your-domain.atlassian.net/wiki/spaces/ARCH/pages/123456
- Status: Published
- Stakeholders notified via @mentions
```

### Example 4: Updating Options (Windsurf)

```
You: Update the MongoDB option in ADR-001 to include performance benchmarks

Windsurf: [Uses update_architecture_decision_record_option tool]

Updated option "MongoDB" with:
- Performance data: 10K writes/sec
- Latency: ~5ms p95
- Scalability: Horizontal sharding
```

### Example 5: Creating Technical Requirements (Claude Desktop)

```
You: Create technical requirements for a user authentication feature

Claude: [Uses create_technical_requirements tool]

Created: TECH-REQ-001
- Feature: User Authentication
- Functional Requirements: Login, logout, password reset
- Non-functional: <2s response time, 99.9% uptime
- Dependencies: OAuth library, email service
```

---

## 🎨 Advanced Features

### Confluence Integration

Several tools support **publishing to Confluence** with:

- ✅ Automatic ADF (Atlassian Document Format) conversion
- ✅ @mention resolution for stakeholders
- ✅ Linked diagrams and code examples
- ✅ Status badges and metadata

**Requirements for Confluence sync:**

- Confluence API credentials in API server config
- Workspace configured with Space Key
- User permissions to create/edit pages

### Search and Discovery

**Keyword search** with relevance scoring:

- Full-text search across all ADR fields
- Highlighted snippets in results
- Relevance scores for ranking

### Technology Standardization

Track your **approved technology stack**:

- Categorize by layer (frontend, backend, database, etc.)
- Mark technologies as approved/deprecated
- Document rationale and alternatives
- Search and filter by category

---

## ⚙️ Configuration

### Environment Variables

| Variable    | Default                     | Description                                     |
| ----------- | --------------------------- | ----------------------------------------------- |
| `API_URL`   | `http://localhost:3000/api` | Backend API base URL                            |
| `LOG_LEVEL` | `info`                      | Logging level: `error`, `warn`, `info`, `debug` |

### Custom API URL

If your API runs on a different port or host:

```json
{
  "mcpServers": {
    "principal-architect": {
      "env": {
        "API_URL": "http://localhost:8080/api"
      }
    }
  }
}
```

### Debug Mode

Enable detailed logging for troubleshooting:

```json
{
  "mcpServers": {
    "principal-architect": {
      "env": {
        "LOG_LEVEL": "debug"
      }
    }
  }
}
```

---

## 🔧 Development

### Project Structure

```
principal-architect-service/
├── apps/
│   └── product-initiatives-api/      # NestJS API backend
├── product-initiatives-mcp/           # MCP server
│   ├── src/
│   │   ├── main.ts                   # Server entry point
│   │   ├── tools/                    # Domain-specific tools
│   │   │   ├── adrs.tools.ts
│   │   │   ├── technical-requirements.tools.ts
│   │   │   ├── product-requirements.tools.ts
│   │   │   └── ...
│   │   └── utils/                    # Shared utilities
│   │       ├── logger.ts
│   │       ├── api-client.ts
│   │       └── error-handler.ts
│   └── README.md
├── libs/                             # Shared libraries
│   ├── resource-schemas/             # JSON schemas
│   ├── mcp-tool-generator/           # Tool generation
│   └── confluence-client/            # Confluence integration
└── dist/                             # Build output
```

### Running Tests

```bash
# Run all tests
npm test

# Run specific domain tests
npx nx test product-initiatives-api

# Run with coverage
npm run test:coverage

# Run e2e tests
npm run test:e2e
```

### Building for Production

```bash
# Build MCP server
npx nx build product-initiatives-mcp

# Build API server
npx nx build product-initiatives-api

# Build all
npm run build
```

### Local Development

```bash
# Start API server (watch mode)
npx nx serve product-initiatives-api

# In another terminal, test MCP server
node dist/product-initiatives-mcp/main.js

# Or use the development build
npx nx serve product-initiatives-mcp
```

---

## 🐛 Troubleshooting

### Common Issues

#### 1. "Connection refused" errors

**Problem:** MCP server can't reach the API backend

**Solution:**

```bash
# Check if API is running
curl http://localhost:3000/api/health

# Start the API if needed
npx nx serve product-initiatives-api
```

#### 2. "Unknown tool" errors

**Problem:** Tool not found or not loaded

**Solution:**

```bash
# Rebuild the MCP server
npx nx build product-initiatives-mcp

# Restart Claude Desktop/Code/Windsurf
```

#### 3. Schema validation errors

**Problem:** Invalid input format

**Solution:**

- Check the tool's input schema in the tool list
- Ensure required fields are provided
- Verify data types match (string, number, boolean)

#### 4. Path issues on Windows

**Problem:** Windows path format not recognized

**Solution:**
Use forward slashes or escaped backslashes:

```json
{
  "command": "node",
  "args": [
    "C:/Users/YourName/principal-architect-service/dist/product-initiatives-mcp/main.js"
  ]
}
```

#### 5. Port conflicts

**Problem:** API server port 3000 already in use

**Solution:**

```bash
# Use different port
PORT=3001 npx nx serve product-initiatives-api

# Update MCP config
"API_URL": "http://localhost:3001/api"
```

### Debug Checklist

- [ ] API server is running (`curl http://localhost:3000/api/health`)
- [ ] MCP server is built (`ls dist/product-initiatives-mcp/main.js`)
- [ ] Config file has correct absolute paths
- [ ] Environment variables are set correctly
- [ ] Claude Desktop/Code/Windsurf has been restarted
- [ ] No port conflicts (check `lsof -i :3000`)
- [ ] Logs show successful tool initialization

### Viewing Logs

**Claude Desktop:**

- Help → Developer Tools → Console

**Claude Code:**

```bash
# Set debug level in config
LOG_LEVEL: debug

# Logs output to stderr
```

**Windsurf:**

- View → Output → MCP Servers

---

## 📚 Related Documentation

- [Product Initiatives MCP Server](./product-initiatives-mcp/README.md)
- [Model Context Protocol Spec](https://modelcontextprotocol.io)
- [NX Monorepo Guide](https://nx.dev)

---

## 🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. **Run quality checks before committing:**

   ```bash
   npm run lint
   npm test
   npm run typecheck
   ```

2. **Follow existing patterns:**

   - Use NX generators for new tools
   - Follow TypeScript strict mode
   - Add tests for new functionality

3. **Commit message format:**
   ```
   feat: add new ADR search capabilities
   fix: resolve Confluence publish error
   docs: update installation instructions
   ```

---

## 📄 License

MIT License

---

## 🆘 Support

**Issues?**

- Check the [Troubleshooting](#troubleshooting) section
- Review logs in your AI tool's developer console
- Verify API server is running and accessible
- Ensure all dependencies are installed

**Questions?**

- Review the [Usage Examples](#usage-examples)
- Check tool descriptions in the [Available Tools](#available-tools) section
- Consult the [MCP specification](https://modelcontextprotocol.io)

**Need Help?**
Open an issue on GitHub with:

- Your environment (Claude Desktop/Code/Windsurf version)
- Config file contents (sanitize sensitive data)
- Relevant logs or error messages
- Steps to reproduce the issue

---

## 🎉 Getting Started Checklist

- [ ] Clone the repository
- [ ] Run `npm install`
- [ ] Build the MCP server: `npx nx build product-initiatives-mcp`
- [ ] Start the API server: `npx nx serve product-initiatives-api`
- [ ] Configure your AI tool (Claude Desktop/Code/Windsurf)
- [ ] Restart your AI tool
- [ ] Test: "List all architecture decision records"
- [ ] Success! 🎊

**Ready to document your architecture decisions? Start with:**

```
"Create an ADR for our first major technical decision"
```