acuity-mcp-server 1.0.0

package/README.md

@@ -0,0 +1,541 @@
+# Acuity MCP Server
+
+Model Context Protocol (MCP) server for Acuity Project Management. Enables LLMs like Claude and Microsoft Copilot to query project data, generate reports, and provide AI-assisted insights.
+
+## Features
+
+- **Dual Transport Support**:
+  - **stdio** - For local clients (Claude Desktop, Cursor)
+  - **HTTP (Streamable HTTP)** - For remote clients (Microsoft Copilot Studio, remote Claude)
+- **Authentication**: OAuth 2.0 Device Authorization Flow with two-phase verification
+- **SSO Support**: Enterprise SSO (SAML, Azure AD, Okta) works automatically
+- **Authorization**: Leverages Hasura row-level security (users only see their accessible data)
+- **Read-Only**: MVP focuses on safe, read-only queries
+- **Secure Storage**: Credentials stored in system keychain (macOS Keychain, Windows Credential Manager)
+- **Container Ready**: Dockerfile included for Azure Container Apps deployment
+- **Core Tools**:
+  - `acuity_init` - Initialize context and get company info
+  - `list_projects` / `get_project` / `search_projects` - Project management
+  - `get_status_reports` - Project status reports
+  - `list_risks` / `get_risk` - Risk management
+  - `list_issues` / `get_issue` - Issue tracking
+  - `list_lessons_learned` / `get_lesson_learned` - Lessons learned
+  - `get_lookup_values` - Departments, categories, lifecycles
+  - `get_dashboard_summary` - Portfolio dashboard data
+
+## Prerequisites
+
+- Node.js 20.x
+- Acuity development environment running:
+  - PostgreSQL (port 5433)
+  - Hasura (port 8080)
+  - Auth0 configuration
+
+## Installation
+
+```bash
+# Install dependencies
+npm install
+
+# Build the server
+npm run build
+```
+
+## Quick Start
+
+### 1. Authenticate (One-time setup)
+
+```bash
+# Run the authentication flow
+npm start init
+# Or directly: node dist/index.js init
+```
+
+This will:
+1. Open your browser to Auth0 login page
+2. Display a verification code (e.g., `ABCD-EFGH`)
+3. After you log in, credentials are stored securely in your system keychain
+
+### 2. Check Authentication Status
+
+```bash
+npm start status
+```
+
+### 3. Configure Your MCP Client
+
+Add to Claude Desktop, Cursor, or other MCP clients (see Configuration section below).
+
+That's it! No manual JWT token copying required.
+
+## Configuration
+
+### Environment Variables
+
+Required in `.env.development`:
+
+```bash
+# Auth0
+AUTH0_DOMAIN=auth.acuityppm.com
+AUTH0_MANAGEMENT_DOMAIN=acuityppm.auth0.com
+AUTH0_MCP_CLIENT_ID=your-native-app-client-id  # Optional: dedicated MCP client
+REACT_APP_AUTH0_CLIENT_ID=your-client-id       # Fallback if AUTH0_MCP_CLIENT_ID not set
+
+# Hasura
+HASURA_GRAPHQL_ENDPOINT=http://localhost:8080/v1/graphql
+
+# MCP Server
+NODE_ENV=development
+LOG_LEVEL=debug  # Set to 'debug' for verbose logging
+```
+
+### Authentication Methods
+
+#### Method 1: Device Authorization Flow (Recommended)
+
+No manual token management required! Run `npm start init` once and credentials are stored securely.
+
+Benefits:
+- No manual JWT copying
+- Automatic token refresh
+- Credentials stored in system keychain
+- Works until you logout or revoke access
+
+#### Method 2: Legacy JWT Token (Deprecated)
+
+For backward compatibility, you can still use `USER_JWT` environment variable:
+
+```bash
+USER_JWT=your-jwt-token-here
+```
+
+To get a JWT token manually:
+1. Log into Acuity web app (http://localhost:3000)
+2. Open browser DevTools → Application → Local Storage
+3. Find the Auth0 token (key like `@@auth0spajs@@::...`)
+4. Copy the `id_token` value
+
+## Usage
+
+### Development Mode
+
+```bash
+# Start in watch mode (auto-reload on changes)
+npm run dev
+```
+
+### Build and Run
+
+```bash
+# Build TypeScript
+npm run build
+
+# Run built version
+npm start
+```
+
+### Type Checking
+
+```bash
+npm run typecheck
+```
+
+## CLI Commands
+
+```bash
+# Start stdio server (for Claude Desktop, Cursor)
+npm start
+
+# Start HTTP server (for Copilot Studio, remote clients)
+npm start http
+npm start http --port 8080  # custom port
+
+# Authenticate via browser (Device Authorization Flow)
+npm start init
+
+# Check authentication status
+npm start status
+
+# Remove stored credentials
+npm start logout
+
+# Show help
+npm start help
+```
+
+## HTTP Server Mode (Remote Clients)
+
+The HTTP mode enables remote clients like Microsoft Copilot Studio and remote Claude instances to connect via Streamable HTTP transport.
+
+### Starting HTTP Server
+
+```bash
+# Build first
+npm run build
+
+# Start on default port 3000
+npm start http
+
+# Start on custom port
+npm start http --port 8080
+```
+
+### Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/mcp` | POST | MCP JSON-RPC requests |
+| `/mcp` | GET | SSE stream (server-to-client) |
+| `/mcp` | DELETE | Close session |
+| `/health` | GET | Health check |
+| `/openapi.yaml` | GET | OpenAPI schema |
+
+### Authentication (HTTP Mode)
+
+HTTP requests require one of:
+
+1. **OAuth 2.0 Bearer Token** (recommended):
+   ```bash
+   curl -X POST http://localhost:3000/mcp \
+     -H "Authorization: Bearer <auth0-jwt-token>" \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"initialize","id":1}'
+   ```
+
+2. **API Key** (for service-to-service):
+   ```bash
+   # Set environment variables first:
+   # MCP_API_KEY=your-secret-key
+   # MCP_SERVICE_EMAIL=service@example.com
+
+   curl -X POST http://localhost:3000/mcp \
+     -H "x-api-key: your-secret-key" \
+     -H "Content-Type: application/json" \
+     -d '{"jsonrpc":"2.0","method":"initialize","id":1}'
+   ```
+
+### Docker Deployment
+
+```bash
+# Build image
+docker build -t acuity-mcp-server .
+
+# Run container
+docker run -p 3000:3000 \
+  -e AUTH0_DOMAIN=acuityppm.auth0.com \
+  -e HASURA_GRAPHQL_ENDPOINT=https://api.acuityppm.com/v1/graphql \
+  acuity-mcp-server
+```
+
+### Azure Container Apps Deployment
+
+```bash
+# Using Azure Developer CLI
+azd init
+azd up
+
+# Or manual deployment
+az containerapp up \
+  --name acuity-mcp \
+  --resource-group your-rg \
+  --image your-registry/acuity-mcp-server:latest \
+  --target-port 3000 \
+  --ingress external
+```
+
+### Microsoft Copilot Studio Integration
+
+1. Go to **Copilot Studio** → **Tools** → **Add tool** → **Model Context Protocol**
+2. Enter server URL: `https://<your-app>.azurecontainerapps.io/mcp`
+3. Select authentication: **OAuth 2.0**
+4. Configure Auth0:
+   - Authorization URL: `https://acuityppm.auth0.com/authorize`
+   - Token URL: `https://acuityppm.auth0.com/oauth/token`
+5. Click **Create** and test connection
+
+## Claude Desktop Configuration
+
+### Option 1: Using npx (Recommended after npm publish)
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "acuity": {
+      "command": "npx",
+      "args": ["-y", "acuity-mcp-server"],
+      "env": {
+        "ACUITY_ENV": "US-1"
+      }
+    }
+  }
+}
+```
+
+**Available environments:**
+- `US-1` - Production US
+- `US-staging` - Staging US
+- `EU-1` - Production EU
+- `UAE-1` - Production UAE
+- `US-2`, `US-3`, `US-5`, `US-6`, `US-7` - US client instances
+- `EU-2`, `EU-3`, `EU-4` - EU client instances
+- `dev` - Local development
+
+### Option 2: Local Development
+
+For development with local source code:
+
+```json
+{
+  "mcpServers": {
+    "acuity": {
+      "command": "node",
+      "args": ["/path/to/acuity/mcp-server/dist/index.js"],
+      "env": {
+        "ACUITY_ENV": "dev"
+      }
+    }
+  }
+}
+```
+
+**Important:** `ACUITY_ENV` is required - you must specify which environment to connect to.
+
+### First-Time Login (Two-Phase Flow)
+
+In Claude Desktop, simply say:
+```
+"Login to Acuity"
+```
+
+**Phase 1 - Get verification code:**
+1. Claude shows: `🔐 Verification Code: XXXX-XXXX`
+2. A browser window opens automatically
+3. **Verify the code in browser matches the code in Claude!**
+4. Log in with your Acuity credentials (or use SSO if configured)
+
+**Phase 2 - Complete authentication:**
+1. After logging in, say: `"continue login"` or `"I've logged in"`
+2. Claude verifies and shows: `✅ Login Successful!`
+
+Credentials are stored securely in your system keychain.
+
+### Example Queries
+
+Try these in Claude Desktop:
+
+```
+"Login to Acuity"           # First-time authentication
+
+"Show me my projects"       # List your projects
+
+"Check my auth status"      # Verify authentication
+
+"Logout from Acuity"        # Clear credentials
+```
+
+## Available Tools
+
+### Authentication Tools
+
+#### acuity_login
+Login to Acuity. Opens a browser for secure OAuth login.
+
+#### acuity_logout
+Logout from Acuity and clear stored credentials.
+
+#### acuity_auth_status
+Check current authentication status.
+
+### Data Tools
+
+#### list_projects
+
+Lists all projects the user has access to.
+
+**Parameters:**
+- `state` (optional): Filter by state (active, hold, completed, cancelled, pending)
+- `health_status` (optional): Filter by health (green, yellow, red, gray)
+- `portfolio_id` (optional): Filter by portfolio
+- `limit` (optional, default: 20): Max results
+- `offset` (optional, default: 0): Pagination offset
+
+#### get_status_reports
+
+Get status reports for projects.
+
+**Parameters:**
+- `project_id` (optional): Specific project ID
+- `limit` (optional, default: 10): Max results
+
+## Architecture
+
+```
+┌──────────────────┐     ┌───────────────────┐
+│  Claude Desktop  │     │  Microsoft Copilot │
+│  Cursor, etc.    │     │  Remote Claude     │
+└────────┬─────────┘     └─────────┬─────────┘
+         │ stdio                   │ HTTPS
+         │                         │
+         ▼                         ▼
+┌─────────────────────────────────────────────┐
+│            Acuity MCP Server                │
+│  ┌─────────────┐    ┌────────────────────┐  │
+│  │ StdioServer │    │ HTTP Server        │  │
+│  │ Transport   │    │ (Streamable HTTP)  │  │
+│  └──────┬──────┘    └──────────┬─────────┘  │
+│         │                      │            │
+│         └──────────┬───────────┘            │
+│                    ▼                        │
+│  ┌─────────────────────────────────────┐   │
+│  │          MCP Core                    │   │
+│  │  - Tool Handlers                     │   │
+│  │  - Session Management                │   │
+│  │  - JWT/API Key Validation            │   │
+│  └─────────────────┬───────────────────┘   │
+└────────────────────┼────────────────────────┘
+                     │
+                     ▼
+          ┌─────────────────┐
+          │ Hasura GraphQL  │
+          │ + Row Security  │
+          └────────┬────────┘
+                   │
+                   ▼
+          ┌─────────────────┐
+          │   PostgreSQL    │
+          └─────────────────┘
+```
+
+## Security
+
+- ✅ OAuth 2.0 Device Authorization Flow with two-phase code verification
+- ✅ Enterprise SSO support (SAML, Azure AD, Okta)
+- ✅ ID Token (JWT) used for Hasura authentication
+- ✅ Credentials stored in system keychain (not in files)
+- ✅ Automatic token refresh (no manual intervention)
+- ✅ Row-level security via Hasura (X-Hasura-Email)
+- ✅ Read-only operations
+- ✅ User scoped to their accessible portfolios
+- ✅ No cross-company data leakage
+
+## Troubleshooting
+
+### "No credentials stored. Run 'init' to authenticate."
+- You haven't authenticated yet
+- Run `npm start init` to authenticate via browser
+
+### "Token expired and no refresh token available"
+- Your refresh token has been revoked or expired
+- Run `npm start init` to re-authenticate
+
+### "Failed to refresh token"
+- Check your internet connection
+- Auth0 may be temporarily unavailable
+- Run `npm start init` to get fresh credentials
+
+### "Could not open browser automatically"
+- Open the displayed URL manually in your browser
+- Enter the verification code shown in terminal
+
+### "Invalid JWT token"
+- Run `npm start status` to check token status
+- If expired, run `npm start init` to re-authenticate
+- Verify Auth0 domain configuration matches
+
+### "GraphQL query failed"
+- Check Hasura is running (`docker-compose up`)
+- Verify endpoint: `http://localhost:8080/v1/graphql`
+- Check user has access to portfolios
+
+### "Project not found"
+- User may not have access to that project
+- Check portfolio memberships in database
+- Verify project ID is correct
+
+### Legacy: "JWT token is required" (USER_JWT mode)
+- Ensure `USER_JWT` is set in environment
+- Token must be valid (not expired)
+- Consider switching to Device Flow: `npm start init`
+
+## Development
+
+### Project Structure
+
+```
+mcp-server/
+├── src/
+│   ├── index.ts              # Entry point + CLI (stdio & http modes)
+│   ├── server/
+│   │   ├── http-server.ts    # Express + Streamable HTTP transport
+│   │   └── mcp-core.ts       # Shared MCP server logic
+│   ├── auth/
+│   │   ├── jwt-validator.ts  # Auth0 JWT validation
+│   │   ├── device-flow.ts    # OAuth 2.0 Device Authorization Flow
+│   │   ├── token-storage.ts  # System keychain credential storage
+│   │   └── http-auth.ts      # HTTP OAuth/API key middleware
+│   ├── clients/
+│   │   └── hasura-client.ts  # GraphQL client (uses ID Token for auth)
+│   ├── tools/
+│   │   ├── init-auth.ts      # Login/logout/status tools
+│   │   ├── acuity-init.ts    # Initialize context
+│   │   ├── list-projects.ts  # List/filter projects
+│   │   ├── get-project.ts    # Get project details
+│   │   ├── search-projects.ts # Search projects
+│   │   ├── get-status-reports.ts
+│   │   ├── list-risks.ts / get-risk.ts
+│   │   ├── list-issues.ts / get-issue.ts
+│   │   ├── list-lessons-learned.ts / get-lesson-learned.ts
+│   │   ├── get-lookup-values.ts
+│   │   └── get-dashboard-summary.ts
+│   ├── types/
+│   │   └── project.ts        # TypeScript types
+│   └── utils/
+│       └── formatters.ts     # Response formatting
+├── openapi.yaml              # OpenAPI schema for Copilot Studio
+├── Dockerfile                # Container build
+├── package.json
+├── tsconfig.json
+└── README.md
+```
+
+### Adding a New Tool
+
+1. Create tool file in `src/tools/`
+2. Define GraphQL query
+3. Implement handler function
+4. Export tool definition with schema
+5. Register in `src/index.ts`
+
+Example:
+
+```typescript
+// src/tools/my-tool.ts
+export const myTool = {
+  name: 'my_tool',
+  description: 'What this tool does',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      param: { type: 'string' }
+    }
+  }
+};
+
+export async function myToolHandler(input, hasuraClient) {
+  // Implementation
+}
+```
+
+## References
+
+- [Authentication Guide](../.claude/docs/MCP_AUTH.md)
+- [Planning Document](../docs/MCP/planning.md)
+- [MCP Documentation](https://modelcontextprotocol.io)
+- [Hasura Permissions](../hasura/metadata/databases/default/tables/)
+- [Auth0 Device Flow](https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow)
+
+## License
+
+ISC

package/dist/auth/device-flow.d.ts

@@ -0,0 +1,46 @@
+/**
+ * OAuth 2.0 Device Authorization Flow for Auth0
+ *
+ * Implements the Device Code flow for CLI/MCP authentication
+ * Reference: https://auth0.com/docs/get-started/authentication-and-authorization-flow/device-authorization-flow
+ */
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete: string;
+    expires_in: number;
+    interval: number;
+}
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    id_token?: string;
+    token_type: string;
+    expires_in: number;
+    scope?: string;
+}
+export interface DeviceFlowConfig {
+    domain: string;
+    clientId: string;
+    audience?: string;
+    scope?: string;
+}
+/**
+ * Request a device code from Auth0
+ */
+export declare function requestDeviceCode(config: DeviceFlowConfig): Promise<DeviceCodeResponse>;
+/**
+ * Poll for access token
+ * Returns token when user completes authorization, or throws on timeout/error
+ */
+export declare function pollForToken(config: DeviceFlowConfig, deviceCode: string, interval: number, expiresIn: number, onPoll?: () => void): Promise<TokenResponse>;
+/**
+ * Refresh an access token using a refresh token
+ */
+export declare function refreshAccessToken(config: DeviceFlowConfig, refreshToken: string): Promise<TokenResponse>;
+/**
+ * Run the complete Device Authorization Flow
+ */
+export declare function runDeviceFlow(config: DeviceFlowConfig): Promise<TokenResponse>;
+//# sourceMappingURL=device-flow.d.ts.map

package/dist/auth/device-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-flow.d.ts","sourceRoot":"","sources":["../../src/auth/device-flow.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,WAAW,kBAAkB;IACjC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,gBAAgB,EAAE,MAAM,CAAC;IACzB,yBAAyB,EAAE,MAAM,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAOD;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA0B7F;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAChC,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,EACjB,MAAM,CAAC,EAAE,MAAM,IAAI,GAClB,OAAO,CAAC,aAAa,CAAC,CAwDxB;AAED;;GAEG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,gBAAgB,EACxB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,CAAC,CAuBxB;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,CAsCpF"}