first commit

2026-02-21 03:10:39 +00:00
commit d0aa0c5d63
174 changed files with 21169 additions and 0 deletions
--- a/.taskmaster/tasks/task_015.md
+++ b/.taskmaster/tasks/task_015.md
@@ -0,0 +1,297 @@
+# Task ID: 15
+
+**Title:** Create MCP Server Profiles Library
+
+**Status:** pending
+
+**Dependencies:** 4, 10
+
+**Priority:** medium
+
+**Description:** Build a library of pre-configured MCP server profiles for popular tools (Slack, Jira, GitHub, Terraform, etc.) with setup guides and permission templates.
+
+**Details:**
+
+Create comprehensive server definitions:
+
+```typescript
+// seed/mcp-servers.ts
+export const mcpServerDefinitions = [
+  {
+    name: 'slack',
+    type: 'slack',
+    displayName: 'Slack',
+    description: 'Access Slack channels, messages, and users',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-slack'],
+    envTemplate: {
+      SLACK_BOT_TOKEN: {
+        description: 'Slack Bot OAuth Token',
+        required: true,
+        secret: true,
+        setupUrl: 'https://api.slack.com/apps',
+        setupGuide: `## Slack MCP Setup\n\n1. Go to https://api.slack.com/apps\n2. Create new app or select existing\n3. Go to OAuth & Permissions\n4. Add scopes: channels:read, channels:history, users:read\n5. Install to workspace\n6. Copy Bot User OAuth Token`
+      },
+      SLACK_TEAM_ID: { description: 'Slack Team/Workspace ID', required: true }
+    },
+    defaultProfiles: [
+      { name: 'read-only', config: { permissions: ['read'] } },
+      { name: 'full-access', config: { permissions: ['read', 'write'] } }
+    ]
+  },
+  {
+    name: 'jira',
+    type: 'jira',
+    displayName: 'Jira',
+    description: 'Access Jira issues, projects, and workflows',
+    command: 'npx',
+    args: ['-y', '@anthropic/mcp-server-jira'],
+    envTemplate: {
+      JIRA_URL: { description: 'Jira instance URL', required: true },
+      JIRA_EMAIL: { description: 'Jira account email', required: true },
+      JIRA_API_TOKEN: {
+        description: 'Jira API Token',
+        required: true,
+        secret: true,
+        setupUrl: 'https://id.atlassian.com/manage-profile/security/api-tokens',
+        setupGuide: `## Jira API Token Setup\n\n1. Go to https://id.atlassian.com/manage-profile/security/api-tokens\n2. Click Create API token\n3. Give it a label (e.g., "mcpctl")\n4. Copy the token`
+      }
+    },
+    defaultProfiles: [
+      { name: 'read-only', config: { permissions: ['read'], projects: ['*'] } },
+      { name: 'project-limited', config: { permissions: ['read', 'write'], projects: [] } }
+    ]
+  },
+  {
+    name: 'github',
+    type: 'github',
+    displayName: 'GitHub',
+    description: 'Access GitHub repositories, issues, and PRs',
+    command: 'npx',
+    args: ['-y', '@modelcontextprotocol/server-github'],
+    envTemplate: {
+      GITHUB_TOKEN: {
+        description: 'GitHub Personal Access Token',
+        required: true,
+        secret: true,
+        setupUrl: 'https://github.com/settings/tokens',
+        setupGuide: `## GitHub PAT Setup\n\n1. Go to https://github.com/settings/tokens\n2. Generate new token (classic)\n3. Select scopes: repo, read:user\n4. Copy token`
+      }
+    }
+  },
+  {
+    name: 'terraform-docs',
+    type: 'terraform',
+    displayName: 'Terraform Documentation',
+    description: 'Access Terraform provider documentation',
+    command: 'npx',
+    args: ['-y', 'terraform-docs-mcp'],
+    envTemplate: {},
+    defaultProfiles: [
+      { name: 'aws-only', config: { providers: ['aws'] } },
+      { name: 'all-providers', config: { providers: ['*'] } }
+    ]
+  }
+];
+```
+
+**Test Strategy:**
+
+Verify all server definitions have required fields. Test setup guides render correctly. Test default profiles work with actual MCP servers.
+
+## Subtasks
+
+### 15.1. Define TypeScript types and write TDD tests for MCP server profile schemas
+
+**Status:** pending  
+**Dependencies:** None  
+
+Create comprehensive TypeScript interfaces and Zod validation schemas for MCP server profile definitions, including tests for all validation rules before implementation.
+
+**Details:**
+
+Create src/shared/src/types/mcp-profiles.ts with TypeScript interfaces:
+
+1. **Core Types**:
+   - `McpServerDefinition` - Main server definition with name, type, displayName, description, command, args, envTemplate, defaultProfiles, networkRequirements
+   - `EnvTemplateVariable` - Environment variable with description, required, secret, setupUrl, setupGuide, pattern (for validation)
+   - `DefaultProfile` - Profile configuration with name, config object, minimumScopes array
+   - `NetworkRequirement` - endpoints, ports, protocols for firewall documentation
+
+2. **Zod Schemas** in src/shared/src/schemas/mcp-profiles.schema.ts:
+   - Validate command is 'npx' or 'docker' or absolute path
+   - Validate envTemplate has at least one required variable for auth types
+   - Validate secret fields don't appear in args array
+   - Validate setupGuide is valid markdown with required sections
+   - Validate minimumScopes for each profile type
+
+3. **TDD Tests** in src/shared/src/__tests__/mcp-profiles.test.ts:
+   - Test valid definitions pass schema validation
+   - Test missing required fields fail validation
+   - Test invalid command types are rejected
+   - Test secret variable exposure in args is detected
+   - Test setupGuide markdown structure validation
+   - Test profile permission escalation detection
+   - Test networkRequirements field validation
+
+Export all types from src/shared/src/index.ts for use by other packages.
+
+### 15.2. Implement DevOps/SaaS MCP server profiles (Slack, Jira, GitHub, Terraform)
+
+**Status:** pending  
+**Dependencies:** 15.1  
+
+Create pre-configured MCP server profile definitions for common DevOps and SaaS tools with complete setup guides, minimum required scopes, and network requirements documentation.
+
+**Details:**
+
+Create src/mcpd/src/seed/mcp-servers/devops.ts with server definitions:
+
+1. **Slack Profile**:
+   - Command: npx -y @modelcontextprotocol/server-slack
+   - Required scopes: channels:read, channels:history, users:read (READ), plus channels:write, chat:write (WRITE)
+   - Network: api.slack.com:443/HTTPS, files.slack.com:443/HTTPS
+   - Profiles: read-only (minimum), full-access (with write scopes)
+   - Setup guide with step-by-step Slack app creation
+
+2. **Jira Profile**:
+   - Command: npx -y @anthropic/mcp-server-jira
+   - Required scopes: read:jira-work, read:jira-user (READ), write:jira-work (WRITE)
+   - Network: *.atlassian.net:443/HTTPS
+   - Profiles: read-only, project-limited (with project filter config)
+   - Setup guide for API token generation
+
+3. **GitHub Profile**:
+   - Command: npx -y @modelcontextprotocol/server-github
+   - Required scopes: repo:read, read:user (READ), repo:write, workflow (WRITE)
+   - Network: api.github.com:443/HTTPS, github.com:443/HTTPS
+   - Profiles: read-only, contributor, admin
+   - Setup guide for PAT creation with fine-grained tokens
+
+4. **Terraform Docs Profile**:
+   - Command: npx -y terraform-docs-mcp
+   - No auth required (public docs)
+   - Network: registry.terraform.io:443/HTTPS
+   - Profiles: aws-only, azure-only, gcp-only, all-providers
+
+Include mock validation endpoints for local testing in src/mcpd/src/seed/mcp-servers/__mocks__/devops-validators.ts
+
+### 15.3. Implement Data Platform MCP server profiles (BigQuery, Snowflake, dbt Cloud, Databricks, Airflow)
+
+**Status:** pending  
+**Dependencies:** 15.1  
+
+Create MCP server profile definitions for critical data platform tools with service account authentication patterns, connection string templates, and BI integration support.
+
+**Details:**
+
+Create src/mcpd/src/seed/mcp-servers/data-platform.ts with server definitions:
+
+1. **BigQuery Profile**:
+   - Command: npx -y @anthropic/mcp-server-bigquery (or community equivalent)
+   - Auth: Service account JSON file upload
+   - envTemplate: GOOGLE_APPLICATION_CREDENTIALS (path to JSON), BQ_PROJECT_ID
+   - Network: bigquery.googleapis.com:443/HTTPS, storage.googleapis.com:443/HTTPS
+   - Profiles: viewer (roles/bigquery.dataViewer), analyst (roles/bigquery.user), admin
+
+2. **Snowflake Profile**:
+   - Auth: Multi-step OAuth or key-pair authentication
+   - envTemplate: SNOWFLAKE_ACCOUNT, SNOWFLAKE_USER, SNOWFLAKE_WAREHOUSE, SNOWFLAKE_PRIVATE_KEY or SNOWFLAKE_PASSWORD
+   - Connection string pattern: snowflake://<user>@<account>/<warehouse>
+   - Network: <account>.snowflakecomputing.com:443/HTTPS
+   - Profiles: reader, analyst, developer
+
+3. **dbt Cloud Profile**:
+   - Command: npx -y @dbt-labs/mcp-server-dbt (or community)
+   - envTemplate: DBT_CLOUD_TOKEN, DBT_CLOUD_ACCOUNT_ID, DBT_CLOUD_PROJECT_ID
+   - Network: cloud.getdbt.com:443/HTTPS
+   - Profiles: viewer, developer, admin
+
+4. **Databricks Profile**:
+   - envTemplate: DATABRICKS_HOST, DATABRICKS_TOKEN, DATABRICKS_CLUSTER_ID (optional)
+   - Network: <workspace>.azuredatabricks.net:443/HTTPS or <workspace>.cloud.databricks.com:443/HTTPS
+   - Profiles: workspace-reader, job-runner, admin
+
+5. **Apache Airflow Profile**:
+   - envTemplate: AIRFLOW_URL, AIRFLOW_USERNAME, AIRFLOW_PASSWORD (basic) or AIRFLOW_API_KEY
+   - Network: <airflow-host>:8080/HTTP or :443/HTTPS
+   - Profiles: viewer, operator, admin
+
+Include connection string builder utilities and validators for each platform.
+
+### 15.4. Implement BI/Analytics tool MCP profiles (Tableau, Looker, Metabase, Grafana)
+
+**Status:** pending  
+**Dependencies:** 15.1  
+
+Create MCP server profile definitions for BI and analytics visualization tools commonly used by data analysts for report automation and dashboard access.
+
+**Details:**
+
+Create src/mcpd/src/seed/mcp-servers/analytics.ts with server definitions:
+
+1. **Tableau Profile**:
+   - Auth: Personal Access Token (PAT) or connected app JWT
+   - envTemplate: TABLEAU_SERVER_URL, TABLEAU_SITE_ID, TABLEAU_TOKEN_NAME, TABLEAU_TOKEN_SECRET
+   - Network: <tableau-server>:443/HTTPS (Tableau Cloud: online.tableau.com)
+   - Profiles: viewer (read dashboards), explorer (create workbooks), creator (full access)
+   - Setup guide for PAT generation in Tableau account settings
+
+2. **Looker Profile**:
+   - Auth: API3 client credentials
+   - envTemplate: LOOKER_BASE_URL, LOOKER_CLIENT_ID, LOOKER_CLIENT_SECRET
+   - Network: <instance>.cloud.looker.com:443/HTTPS
+   - Profiles: viewer, developer, admin
+   - Setup guide for API3 key creation
+
+3. **Metabase Profile**:
+   - Auth: Session token or API key
+   - envTemplate: METABASE_URL, METABASE_USERNAME, METABASE_PASSWORD or METABASE_API_KEY
+   - Network: <metabase-host>:3000/HTTP or :443/HTTPS
+   - Profiles: viewer, analyst, admin
+   - Note: Self-hosted vs Cloud configuration differences
+
+4. **Grafana Profile**:
+   - Auth: API key or service account token
+   - envTemplate: GRAFANA_URL, GRAFANA_API_KEY or GRAFANA_SERVICE_ACCOUNT_TOKEN
+   - Network: <grafana-host>:3000/HTTP or :443/HTTPS
+   - Profiles: viewer, editor, admin
+   - Setup guide for service account token creation
+
+All profiles should include query/export permissions appropriate for analyst workflows (read dashboards, export data, schedule reports where supported).
+
+### 15.5. Create profile registry, validation service, and network requirements documentation generator
+
+**Status:** pending  
+**Dependencies:** 15.2, 15.3, 15.4  
+
+Build the central profile registry that indexes all MCP server definitions, provides validation services, and generates network requirements documentation for firewall planning.
+
+**Details:**
+
+Create src/mcpd/src/services/mcp-profile-registry.ts:
+
+1. **McpProfileRegistry Class**:
+   - `getAllDefinitions()` - Returns all registered MCP server definitions
+   - `getDefinitionByName(name: string)` - Lookup by server name
+   - `getDefinitionsByCategory(category: 'devops' | 'data-platform' | 'analytics')` - Filter by category
+   - `searchDefinitions(query: string)` - Search by name, description, or tags
+   - `validateDefinition(def: McpServerDefinition)` - Validate against Zod schema
+   - `registerCustomDefinition(def: McpServerDefinition)` - Add user-defined servers
+
+2. **ProfileValidationService** in src/mcpd/src/services/profile-validation.ts:
+   - `validateCredentials(serverName: string, env: Record<string, string>)` - Test credentials with mock endpoints
+   - `checkMinimumScopes(serverName: string, profile: string)` - Verify profile has required scopes
+   - `detectPermissionEscalation(base: string[], requested: string[])` - Security check for scope expansion
+
+3. **NetworkDocsGenerator** in src/mcpd/src/services/network-docs-generator.ts:
+   - `generateFirewallRules(serverNames: string[])` - Output firewall rules in various formats (iptables, AWS SG, Azure NSG)
+   - `generateNetworkDiagram(projectName: string)` - Mermaid diagram of network flows
+   - `exportToCSV()` - Export all endpoints/ports/protocols for firewall team
+
+4. **Seed Database Integration**:
+   - Update src/mcpd/src/seed/index.ts to load all profile definitions
+   - Create `seedMcpServerLibrary()` function that populates database from profile registry
+   - Support incremental updates when new profiles are added
+
+Export registry and services from src/mcpd/src/index.ts