acuity-mcp-server 1.0.0 → 1.0.1

package/README.md

@@ -1,263 +1,10 @@
 # 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
-```
+Model Context Protocol (MCP) server for [Acuity PPM](https://acuityppm.com). Enables LLMs like Claude to query project data, generate reports, and provide AI-assisted insights.
 
 ## 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`):
+### 1. Configure Claude Desktop
 
 ```json
 {
@@ -266,275 +13,41 @@ Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_
       "command": "npx",
       "args": ["-y", "acuity-mcp-server"],
       "env": {
-        "ACUITY_ENV": "US-1"
+        "ACUITY_ENV": "Ask SUPPORT"
       }
     }
   }
 }
 ```
 
-**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"
-      }
-    }
-  }
-}
-```
+### 2. Restart Claude Desktop
 
-**Important:** `ACUITY_ENV` is required - you must specify which environment to connect to.
+After saving the config, restart Claude Desktop to load the MCP server.
 
-### First-Time Login (Two-Phase Flow)
+### 3. Login
 
-In Claude Desktop, simply say:
+In Claude Desktop, 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.
+A browser window will open. Complete the login, then say "continue login" to finish authentication.
 
-#### acuity_auth_status
-Check current authentication status.
+## Example Queries
 
-### Data Tools
+Once logged in, try these in Claude Desktop:
 
-#### 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    │
-          └─────────────────┘
-```
+- "Show me my projects"
+- "List active projects"
+- "Get status reports for project X"
+- "What are the current risks?"
 
 ## 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)
+- OAuth 2.0 Device Authorization Flow
+- Credentials stored in system keychain
+- Read-only operations
+- Row-level security (users only see their accessible data)
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuity-mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for Acuity Project Management - enables LLM access to project data",
   "type": "module",
   "main": "dist/index.js",