first commit
This commit is contained in:
Michal
410
.taskmaster/tasks/task_001.md
Normal file
410
.taskmaster/tasks/task_001.md
Normal file
@@ -0,0 +1,410 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user