mcpctl/.taskmaster/tasks/task_015.md

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:

// 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://@/
   • Network: .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: .azuredatabricks.net:443/HTTPS or .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: :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: :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: .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: :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: :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