# Task ID: 1

**Title:** Initialize Project Structure and Core Dependencies

**Status:** pending

**Dependencies:** None

**Priority:** high

**Description:** Set up the monorepo structure for mcpctl with CLI client, mcpd server, and shared libraries. Configure TypeScript, ESLint, and build tooling.

**Details:**

Create a monorepo using pnpm workspaces or npm workspaces with the following structure:

```
mcpctl/
├── src/
│   ├── cli/              # mcpctl CLI tool
│   ├── mcpd/             # Backend daemon server
│   ├── shared/           # Shared types, utilities, constants
│   └── local-proxy/      # Local LLM proxy component
├── docker/
│   └── docker-compose.yml
├── package.json
├── tsconfig.base.json
└── pnpm-workspace.yaml
```

Dependencies to install:
- TypeScript 5.x
- Commander.js for CLI
- Express/Fastify for mcpd HTTP server
- Zod for schema validation
- Winston/Pino for logging
- Prisma or Drizzle for database ORM

Create base tsconfig.json with strict mode, ES2022 target, and module resolution settings. Set up shared ESLint config with TypeScript rules.

**Test Strategy:**

Verify project builds successfully with `pnpm build`. Ensure all packages compile without errors. Test workspace linking works correctly between packages.

## Subtasks

### 1.1. Initialize pnpm workspace monorepo with future-proof directory structure

**Status:** pending  
**Dependencies:** None  

Create the complete monorepo directory structure using pnpm workspaces that accommodates all 18 planned tasks without requiring future refactoring.

**Details:**

Create root package.json with pnpm workspaces configuration. Create pnpm-workspace.yaml defining all workspace packages. Initialize the following directory structure:

```
mcpctl/
├── src/
│   ├── cli/              # mcpctl CLI tool (Task 7-10)
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   ├── mcpd/             # Backend daemon server (Task 3-6, 14, 16)
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   ├── shared/           # Shared types, utils, constants, validation
│   │   ├── src/
│   │   │   ├── types/    # TypeScript interfaces/types
│   │   │   ├── utils/    # Utility functions
│   │   │   ├── constants/# Shared constants
│   │   │   ├── validation/ # Zod schemas
│   │   │   └── index.ts  # Barrel export
│   │   ├── tests/
│   │   └── package.json
│   ├── local-proxy/      # Local LLM proxy (Task 11-13)
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   └── db/               # Database package (Task 2)
│       ├── src/
│       ├── prisma/       # Schema and migrations
│       ├── seed/         # Seed data
│       ├── tests/
│       └── package.json
├── docker/
│   └── docker-compose.yml  # Local dev services (postgres)
├── tests/
│   ├── e2e/              # End-to-end tests (Task 18)
│   └── integration/      # Integration tests
├── docs/                 # Documentation (Task 18)
├── package.json          # Root workspace config
├── pnpm-workspace.yaml
└── turbo.json           # Optional: Turborepo for build orchestration
```

Each package should have:
- Empty src/index.ts with barrel export pattern ready
- Empty tests/ directory
- package.json with correct workspace dependencies (@mcpctl/shared, @mcpctl/db)

Use dependency injection patterns from the start by creating interfaces in shared/src/types/ for key services.
<info added on 2026-02-21T02:33:52.473Z>
CRITICAL STRUCTURAL CHANGE: The monorepo workspace packages directory has been renamed from `packages/` to `src/`. All path references in this subtask must use `src/` instead of `packages/`.

Updated directory structure to implement:

```
mcpctl/
├── src/                      # All application source code (pnpm workspace packages)
│   ├── cli/                  # @mcpctl/cli - CLI tool (Task 7-10)
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   ├── mcpd/                 # @mcpctl/mcpd - Backend daemon (Task 3-6, 14, 16)
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   ├── shared/               # @mcpctl/shared - Shared types, utils, constants, validation
│   │   ├── src/
│   │   │   ├── types/        # TypeScript interfaces/types
│   │   │   ├── utils/        # Utility functions
│   │   │   ├── constants/    # Shared constants
│   │   │   ├── validation/   # Zod schemas
│   │   │   └── index.ts      # Barrel export
│   │   ├── tests/
│   │   └── package.json
│   ├── local-proxy/          # @mcpctl/local-proxy - LLM proxy (Task 11-13)
│   │   ├── src/
│   │   ├── tests/
│   │   └── package.json
│   └── db/                   # @mcpctl/db - Database/Prisma (Task 2)
│       ├── src/
│       ├── prisma/           # Schema and migrations
│       ├── seed/             # Seed data
│       ├── tests/
│       └── package.json
├── deploy/                   # Deployment configs (docker-compose, k8s manifests)
│   ├── docker-compose.yml
│   ├── docker-compose.dev.yml
│   └── Dockerfile.*
├── docs/                     # Documentation (Task 18)
├── tests/                    # E2E and integration tests
│   ├── e2e/
│   └── integration/
├── package.json              # Root workspace config
├── pnpm-workspace.yaml       # Points to src/*
├── tsconfig.base.json
├── eslint.config.js
├── vitest.workspace.ts
└── turbo.json               # Optional: Turborepo for build orchestration
```

The pnpm-workspace.yaml should contain: `packages: ["src/*"]`

Key differences from previous structure:
- `packages/` renamed to `src/` for cleaner separation of app source from project management files
- `docker/` renamed to `deploy/` with additional files (docker-compose.dev.yml, Dockerfile.*)
- Added root config files: eslint.config.js, vitest.workspace.ts
- All workspace package references in pnpm-workspace.yaml use `src/*` pattern
</info added on 2026-02-21T02:33:52.473Z>

### 1.2. Configure TypeScript with strict mode and project references

**Status:** pending  
**Dependencies:** 1.1  

Set up TypeScript configuration with strict mode, ES2022 target, and proper project references for monorepo build orchestration.

**Details:**

Create root tsconfig.base.json with shared compiler options:
```json
{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "lib": ["ES2022"],
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "declaration": true,
    "declarationMap": true,
    "sourceMap": true,
    "composite": true,
    "incremental": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noImplicitReturns": true,
    "noFallthroughCasesInSwitch": true,
    "exactOptionalPropertyTypes": true,
    "noUncheckedIndexedAccess": true
  }
}
```

Create package-specific tsconfig.json in each package that extends the base and sets appropriate paths:
- cli/tsconfig.json: outDir: dist, references to shared and db
- mcpd/tsconfig.json: outDir: dist, references to shared and db
- shared/tsconfig.json: outDir: dist (no references, it's the base)
- local-proxy/tsconfig.json: references to shared
- db/tsconfig.json: references to shared

Create tsconfig.json at root with project references to all packages for unified builds.

Install TypeScript 5.x as devDependency in root package.json.

### 1.3. Set up Vitest testing framework with workspace configuration

**Status:** pending  
**Dependencies:** 1.2  

Configure Vitest as the test framework across all packages with proper workspace setup, coverage reporting, and test-driven development infrastructure.

**Details:**

Install Vitest and related packages at root level:
- vitest
- @vitest/coverage-v8
- @vitest/ui (optional, for visual test running)

Create root vitest.config.ts:
```typescript
import { defineConfig } from 'vitest/config';

export default defineConfig({
  test: {
    globals: true,
    coverage: {
      provider: 'v8',
      reporter: ['text', 'json', 'html'],
      exclude: ['**/node_modules/**', '**/dist/**', '**/*.config.*']
    },
    include: ['src/*/tests/**/*.test.ts', 'tests/**/*.test.ts'],
    testTimeout: 10000
  }
});
```

Create vitest.workspace.ts for workspace-aware testing:
```typescript
import { defineWorkspace } from 'vitest/config';

export default defineWorkspace([
  'src/cli',
  'src/mcpd',
  'src/shared',
  'src/local-proxy',
  'src/db'
]);
```

Create per-package vitest.config.ts files that extend root config.

Add npm scripts to root package.json:
- "test": "vitest"
- "test:run": "vitest run"
- "test:coverage": "vitest run --coverage"
- "test:ui": "vitest --ui"

Create initial test file in src/shared/tests/index.test.ts to verify setup works:
```typescript
import { describe, it, expect } from 'vitest';

describe('shared package', () => {
  it('should be configured correctly', () => {
    expect(true).toBe(true);
  });
});
```

### 1.4. Configure ESLint with TypeScript rules and docker-compose for local development

**Status:** pending  
**Dependencies:** 1.2  

Set up shared ESLint configuration with TypeScript-aware rules, Prettier integration, and docker-compose.yml for local PostgreSQL database.

**Details:**

Install ESLint and plugins at root:
- eslint
- @typescript-eslint/parser
- @typescript-eslint/eslint-plugin
- eslint-config-prettier
- eslint-plugin-import

Create eslint.config.js (flat config, ESLint 9+):
```javascript
import tseslint from '@typescript-eslint/eslint-plugin';
import tsparser from '@typescript-eslint/parser';

export default [
  {
    files: ['src/*/src/**/*.ts'],
    languageOptions: {
      parser: tsparser,
      parserOptions: {
        project: ['./src/*/tsconfig.json'],
        tsconfigRootDir: import.meta.dirname
      }
    },
    plugins: { '@typescript-eslint': tseslint },
    rules: {
      '@typescript-eslint/explicit-function-return-type': 'error',
      '@typescript-eslint/no-explicit-any': 'error',
      '@typescript-eslint/no-unused-vars': 'error',
      '@typescript-eslint/strict-boolean-expressions': 'error',
      'no-console': ['warn', { allow: ['warn', 'error'] }]
    }
  }
];
```

Create deploy/docker-compose.yml for local development:
```yaml
version: '3.8'
services:
  postgres:
    image: postgres:16-alpine
    container_name: mcpctl-postgres
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: mcpctl
      POSTGRES_PASSWORD: mcpctl_dev
      POSTGRES_DB: mcpctl
    volumes:
      - mcpctl-pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U mcpctl"]
      interval: 5s
      timeout: 5s
      retries: 5

volumes:
  mcpctl-pgdata:
```

Add scripts to root package.json:
- "lint": "eslint src/*/src/**/*.ts"
- "lint:fix": "eslint src/*/src/**/*.ts --fix"
- "db:up": "docker-compose -f deploy/docker-compose.yml up -d"
- "db:down": "docker-compose -f deploy/docker-compose.yml down"

Create .env.example at root with DATABASE_URL template:
```
DATABASE_URL="postgresql://mcpctl:mcpctl_dev@localhost:5432/mcpctl"
```

### 1.5. Install core dependencies and perform security/architecture review

**Status:** pending  
**Dependencies:** 1.1, 1.3, 1.4  

Install all required production dependencies across packages, run security audit, and validate the directory structure supports all 18 planned tasks.

**Details:**

Install dependencies per package:

**src/cli/package.json:**
- commander (CLI framework)
- chalk (colored output)
- js-yaml (YAML parsing)
- inquirer (interactive prompts)

**src/mcpd/package.json:**
- fastify (HTTP server)
- @fastify/cors, @fastify/helmet, @fastify/rate-limit (middleware)
- zod (schema validation) - also add to shared
- pino (logging, built into Fastify)

**src/shared/package.json:**
- zod (shared validation schemas)

**src/db/package.json:**
- prisma (ORM)
- @prisma/client

**src/local-proxy/package.json:**
- @modelcontextprotocol/sdk (MCP protocol)

**Root devDependencies:**
- typescript
- vitest, @vitest/coverage-v8
- eslint and plugins (already specified)
- tsx (for running TypeScript directly)
- rimraf (cross-platform rm -rf for clean scripts)

**Security Review Checklist:**
1. Run 'pnpm audit' and verify no high/critical vulnerabilities
2. Verify .gitignore excludes: .env, node_modules, dist, *.log
3. Verify .env.example has no real secrets, only templates
4. Ensure no API keys or secrets in any committed files
5. Document security audit results in SECURITY_AUDIT.md

**Architecture Review Checklist:**
1. Verify structure supports Task 2 (db package with prisma/)
2. Verify structure supports Tasks 3-6 (mcpd with src/routes/, src/services/)
3. Verify structure supports Tasks 7-10 (cli with src/commands/)
4. Verify structure supports Tasks 11-13 (local-proxy with src/providers/)
5. Verify tests/ directories exist at package and root level
6. Verify dependency injection interfaces are defined in shared/src/types/
7. Verify barrel exports in shared/src/index.ts
8. Document architecture decisions in ARCHITECTURE.md
