ryan-norman-cmm/principal-architect-service

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

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

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

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

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

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

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

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

2. Add MCP server configuration:

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

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:

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

5. Verify Installation:

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

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

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

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

Technical Requirements

5 tools for feature requirements:

Product Requirements

5 tools for product specs:

Business Rule Documents

4 tools for business logic:

Technical Estimates

4 tools for effort estimation:

Initiative Resources

4 tools for managing initiatives:

Initiative Releases

5 tools for release planning:

Technology Selections

8 tools for technology decisions:

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

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

Custom API URL

If your API runs on a different port or host:

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

Debug Mode

Enable detailed logging for troubleshooting:

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

# 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

# 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

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

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

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

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

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

# Set debug level in config
LOG_LEVEL: debug

# Logs output to stderr

Windsurf:

• View → Output → MCP Servers

📚 Related Documentation

• Model Context Protocol Spec
• NX Monorepo Guide

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Run quality checks before committing:

   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 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
• Check tool descriptions in the Available Tools section
• Consult the MCP specification

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"