@breadstone/archipel-mcp 0.0.1

package/src/knowledge/testingPattern.js

@@ -0,0 +1,356 @@
+"use strict";
+/**
+ * Static knowledge content for the Archipel testing pattern.
+ * Returned by the get-testing-pattern tool.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TESTING_PATTERN_KNOWLEDGE = void 0;
+exports.TESTING_PATTERN_KNOWLEDGE = `# Archipel Testing Pattern
+
+## Overview
+
+Archipel uses **Vitest** for unit and integration tests with **vi mocking**. Tests follow
+the Arrange-Act-Assert (AAA) pattern with descriptive \`describe\`/\`it\` blocks. Each test
+file covers a single class or module.
+
+## Test Framework
+
+- **Runner:** Vitest
+- **Mocking:** \`vi.fn()\`, \`vi.mock()\`, \`vi.spyOn()\`
+- **Assertions:** Vitest built-in (\`expect\`)
+- **E2E:** Supertest against a bootstrapped NestJS app
+
+## File Naming & Location
+
+| Test Type | File Pattern | Location |
+|-----------|-------------|----------|
+| Unit test | \`*.spec.ts\` | Next to the source file |
+| E2E test | \`*.e2e-spec.ts\` | \`test/\` directory |
+
+## Basic Test Structure
+
+\`\`\`typescript
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('UserService', () => {
+
+  // #region Fields
+
+  let service: UserService;
+  let mockRepository: { execute: ReturnType<typeof vi.fn> };
+  let mockMappingService: { map: ReturnType<typeof vi.fn> };
+
+  // #endregion
+
+  // #region Methods
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+
+    mockRepository = {
+      execute: vi.fn(),
+    };
+
+    mockMappingService = {
+      map: vi.fn(),
+    };
+
+    service = new UserService(
+      mockRepository as unknown as UserRepository,
+      mockMappingService as unknown as MappingService,
+    );
+  });
+
+  describe('findById', () => {
+    it('should return entity when user exists', async () => {
+      // arrange
+      const mockUser = { id: '1', email: 'test@example.com', name: 'Test' };
+      mockRepository.execute.mockResolvedValue(mockUser);
+
+      // act
+      const result = await service.findById('1');
+
+      // assert
+      expect(result).toEqual(mockUser);
+      expect(mockRepository.execute).toHaveBeenCalledOnce();
+    });
+
+    it('should throw UserNotFoundError when user does not exist', async () => {
+      // arrange
+      mockRepository.execute.mockResolvedValue(null);
+
+      // act & assert
+      await expect(() => service.findById('nonexistent'))
+        .rejects.toThrow(UserNotFoundError);
+    });
+  });
+
+  // #endregion
+
+});
+\`\`\`
+
+## Mocking Patterns
+
+### Mocking Prisma Delegates (for Repository Tests)
+
+\`\`\`typescript
+vi.mock('@prisma/client/runtime/client', () => ({
+  PrismaClientKnownRequestError: class PrismaClientKnownRequestError extends Error {
+    public code: string;
+    public meta?: Record<string, unknown>;
+    public clientVersion: string;
+    public constructor(message: string, opts: { code: string; clientVersion: string; meta?: Record<string, unknown> }) {
+      super(message);
+      this.name = 'PrismaClientKnownRequestError';
+      this.code = opts.code;
+      this.clientVersion = opts.clientVersion;
+      this.meta = opts.meta;
+    }
+  },
+  PrismaClientUnknownRequestError: class PrismaClientUnknownRequestError extends Error {
+    public clientVersion: string;
+    public constructor(message: string, opts: { clientVersion: string }) {
+      super(message);
+      this.name = 'PrismaClientUnknownRequestError';
+      this.clientVersion = opts.clientVersion;
+    }
+  },
+}));
+\`\`\`
+
+### Creating a Mock Delegate
+
+\`\`\`typescript
+type MockDelegate = Record<
+  | 'aggregate' | 'count' | 'create' | 'createMany' | 'createManyAndReturn'
+  | 'delete' | 'deleteMany' | 'findFirst' | 'findFirstOrThrow'
+  | 'findMany' | 'findUnique' | 'findUniqueOrThrow'
+  | 'groupBy' | 'update' | 'updateMany' | 'upsert',
+  ReturnType<typeof vi.fn>
+>;
+
+function createMockDelegate(): MockDelegate {
+  return {
+    findUnique: vi.fn(),
+    findFirst: vi.fn(),
+    findMany: vi.fn(),
+    create: vi.fn(),
+    createMany: vi.fn(),
+    createManyAndReturn: vi.fn(),
+    update: vi.fn(),
+    updateMany: vi.fn(),
+    upsert: vi.fn(),
+    delete: vi.fn(),
+    deleteMany: vi.fn(),
+    aggregate: vi.fn(),
+    count: vi.fn(),
+    groupBy: vi.fn(),
+    findFirstOrThrow: vi.fn(),
+    findUniqueOrThrow: vi.fn(),
+  };
+}
+\`\`\`
+
+### Mocking DatabaseService
+
+\`\`\`typescript
+const mockDb = {
+  transactionCallback: vi.fn(),
+  client: {
+    user: createMockDelegate(),
+  },
+} as unknown as DatabaseService;
+\`\`\`
+
+### Mocking a Query
+
+\`\`\`typescript
+const mockQuery = {
+  name: 'findUserById',
+  run: vi.fn().mockResolvedValue({ id: '1', email: 'test@example.com' }),
+};
+\`\`\`
+
+## Repository Test Pattern
+
+\`\`\`typescript
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+// Mock Prisma runtime errors BEFORE importing test subject
+vi.mock('@prisma/client/runtime/client', () => ({ /* ... */ }));
+import { PrismaClientKnownRequestError } from '@prisma/client/runtime/client';
+
+describe('UserRepository', () => {
+
+  let repository: TestRepository;
+  let mockModel: MockDelegate;
+  let mockDb: DatabaseService;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    mockModel = createMockDelegate();
+    mockDb = { transactionCallback: vi.fn() } as unknown as DatabaseService;
+    repository = new TestRepository(mockDb, mockModel);
+  });
+
+  describe('execute', () => {
+    it('should execute a query against the model', async () => {
+      // arrange
+      const mockQuery = {
+        name: 'testQuery',
+        run: vi.fn().mockResolvedValue({ id: '1' }),
+      };
+
+      // act
+      const result = await repository.execute(mockQuery);
+
+      // assert
+      expect(mockQuery.run).toHaveBeenCalledWith(mockModel);
+      expect(result).toEqual({ id: '1' });
+    });
+
+    it('should wrap PrismaClientKnownRequestError as RepositoryError', async () => {
+      // arrange
+      const prismaError = new PrismaClientKnownRequestError('Not found', {
+        code: 'P2025',
+        clientVersion: '6.0.0',
+      });
+      const mockQuery = {
+        name: 'failingQuery',
+        run: vi.fn().mockRejectedValue(prismaError),
+      };
+
+      // act & assert
+      await expect(() => repository.execute(mockQuery))
+        .rejects.toThrow(RepositoryError);
+    });
+  });
+
+});
+\`\`\`
+
+## Service Test Pattern
+
+\`\`\`typescript
+describe('ProductService', () => {
+
+  let service: ProductService;
+  let mockRepo: { execute: ReturnType<typeof vi.fn> };
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+    mockRepo = { execute: vi.fn() };
+    service = new ProductService(mockRepo as unknown as ProductRepository);
+  });
+
+  describe('findById', () => {
+    it('should return entity when found', async () => {
+      // arrange
+      const expected = { id: '1', name: 'Product A', barcode: '123' };
+      mockRepo.execute.mockResolvedValue(expected);
+
+      // act
+      const result = await service.findById('1');
+
+      // assert
+      expect(result).toEqual(expected);
+    });
+
+    it('should throw domain error when not found', async () => {
+      // arrange
+      mockRepo.execute.mockResolvedValue(null);
+
+      // act & assert
+      await expect(() => service.findById('unknown'))
+        .rejects.toThrow(ProductNotFoundError);
+    });
+  });
+
+});
+\`\`\`
+
+## Mapping Profile Test Pattern
+
+\`\`\`typescript
+describe('ProductMappingProfile', () => {
+
+  let mappingService: MappingService;
+
+  beforeEach(() => {
+    mappingService = new MappingService();
+    const profile = new ProductMappingProfile();
+    mappingService.registerProfile(profile);
+  });
+
+  it('should map input to response correctly', () => {
+    // arrange
+    const input: IProductMappingInput = {
+      id: '1',
+      barcode: '123',
+      name: 'Product A',
+      categoryId: 'cat-1',
+      createdAt: new Date('2026-01-01'),
+    };
+
+    // act
+    const result = mappingService.map(PRODUCT_MAPPING_KEY, input);
+
+    // assert
+    expect(result).toBeInstanceOf(ProductResponse);
+    expect(result.id).toBe('1');
+    expect(result.barcode).toBe('123');
+    expect(result.name).toBe('Product A');
+  });
+
+});
+\`\`\`
+
+## Test Conventions
+
+### Comments
+
+\`\`\`typescript
+// Use AAA comments:
+// arrange — set up test data and mocks
+// act — call the method under test
+// act & assert — when the assertion is on the thrown error
+// assert — verify the outcome
+\`\`\`
+
+### Regions
+
+\`\`\`typescript
+describe('MyClass', () => {
+
+  // #region Fields
+  let service: MyService;
+  // #endregion
+
+  // #region Methods
+  beforeEach(() => { ... });
+
+  describe('methodName', () => { ... });
+  // #endregion
+
+});
+\`\`\`
+
+### Naming
+
+- \`describe\` blocks: Class name or method name
+- \`it\` blocks: \`'should <expected behavior> when <condition>'\`
+
+## Rules
+
+1. **Every public service method needs at least one happy-path and one failure-path test.**
+2. **Use \`vi.restoreAllMocks()\` in \`beforeEach\`** — prevent mock leakage between tests.
+3. **Mock at the boundary** — mock repositories in service tests, mock delegates in repository tests.
+4. **AAA pattern** — clearly separate arrange, act, assert with comments.
+5. **\`vi.mock()\` for modules must appear before imports** of the mocked module.
+6. **No real database in unit tests** — use mocks. Use Testcontainers for integration tests.
+7. **Assert on behavior, not implementation** — verify return values and thrown errors, not internal calls
+   (unless the call IS the behavior, e.g., verifying a repository was called).
+8. **Use \`mockResolvedValue\` / \`mockRejectedValue\`** for async mocks.
+`;
+//# sourceMappingURL=testingPattern.js.map

package/src/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/src/main.js

@@ -0,0 +1,226 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mcp_js_1 = require("@modelcontextprotocol/sdk/server/mcp.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const zod_1 = require("zod");
+const DocsLoader_1 = require("./DocsLoader");
+const configPattern_1 = require("./knowledge/configPattern");
+const dtoPattern_1 = require("./knowledge/dtoPattern");
+const errorHandlingPattern_1 = require("./knowledge/errorHandlingPattern");
+const guardPattern_1 = require("./knowledge/guardPattern");
+const mappingPattern_1 = require("./knowledge/mappingPattern");
+const modulePattern_1 = require("./knowledge/modulePattern");
+const queryPattern_1 = require("./knowledge/queryPattern");
+const repositoryPattern_1 = require("./knowledge/repositoryPattern");
+const testingPattern_1 = require("./knowledge/testingPattern");
+// #region Fields
+const SERVER_NAME = 'archipel-mcp';
+const SERVER_VERSION = '0.0.1';
+// #endregion
+// #region Bootstrap
+async function main() {
+    const docsLoader = new DocsLoader_1.DocsLoader();
+    docsLoader.load();
+    const server = new mcp_js_1.McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerTools(server, docsLoader);
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    process.stderr.write(`[${SERVER_NAME}] Server running on stdio\n`);
+}
+// #endregion
+// #region Tool Registration
+function registerTools(server, docsLoader) {
+    // --- list-packages ---
+    server.tool('list-packages', 'Lists all available Archipel platform packages with their descriptions and tags.', {}, async () => {
+        const packages = Array.from(docsLoader.packages.values()).map((packageDoc) => ({
+            name: packageDoc.name,
+            package: packageDoc.packageScope,
+            description: packageDoc.description,
+            tags: packageDoc.tags,
+        }));
+        return {
+            content: [{ type: 'text', text: JSON.stringify(packages, null, 2) }],
+        };
+    });
+    // --- get-package-doc ---
+    server.tool('get-package-doc', 'Gets the full documentation (overview + API reference) for a specific Archipel platform package.', {
+        packageName: zod_1.z.string().describe('The package directory name (e.g. "platform-core", "platform-database").'),
+    }, async (params) => {
+        const packageDoc = docsLoader.packages.get(params.packageName);
+        if (!packageDoc) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Package "${params.packageName}" not found. Use the list-packages tool to see available packages.`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const sections = [
+            `# ${packageDoc.title}`,
+            '',
+            `> ${packageDoc.description}`,
+            '',
+            `**Package:** \`${packageDoc.packageScope}\``,
+        ];
+        if (packageDoc.tags.length > 0) {
+            sections.push(`**Tags:** ${packageDoc.tags.join(', ')}`);
+        }
+        sections.push('', packageDoc.content);
+        if (packageDoc.apiContent) {
+            sections.push('', '---', '', '## API Reference', '', packageDoc.apiContent);
+        }
+        return {
+            content: [{ type: 'text', text: sections.join('\n') }],
+        };
+    });
+    // --- search-docs ---
+    server.tool('search-docs', 'Searches across all Archipel platform documentation by keyword or phrase.', {
+        query: zod_1.z.string().describe('The search query to match against package names, descriptions, tags, and content.'),
+    }, async (params) => {
+        const results = docsLoader.search(params.query);
+        if (results.length === 0) {
+            return {
+                content: [{ type: 'text', text: `No documentation found matching: "${params.query}"` }],
+            };
+        }
+        const summary = results
+            .map((packageDoc) => [
+            `## ${packageDoc.title}`,
+            `**Package:** \`${packageDoc.packageScope}\``,
+            '',
+            packageDoc.description,
+            '',
+            packageDoc.content,
+        ].join('\n'))
+            .join('\n\n---\n\n');
+        return {
+            content: [
+                { type: 'text', text: `Found ${results.length} result(s) for "${params.query}":\n\n${summary}` },
+            ],
+        };
+    });
+    // --- get-query-pattern ---
+    server.tool('get-query-pattern', 'Returns the Archipel query pattern documentation — interfaces, factories, rules, and examples. Optionally tailored to a specific Prisma model.', {
+        modelName: zod_1.z
+            .string()
+            .optional()
+            .describe('Prisma model name (e.g. "User", "Order"). If provided, generates model-specific examples.'),
+        fields: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('Field names of the model (e.g. ["id", "email", "name", "createdAt"]). Used with modelName for tailored examples.'),
+    }, async (params) => {
+        let content = queryPattern_1.QUERY_PATTERN_KNOWLEDGE;
+        if (params.modelName && params.fields && params.fields.length > 0) {
+            content += '\n\n' + (0, queryPattern_1.QUERY_PATTERN_WITH_MODEL)(params.modelName, params.fields);
+        }
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    });
+    // --- get-repository-pattern ---
+    server.tool('get-repository-pattern', 'Returns the Archipel repository class pattern — how to create a RepositoryBase subclass with correct generics, module registration, and service injection. Optionally tailored to a specific Prisma model.', {
+        modelName: zod_1.z
+            .string()
+            .optional()
+            .describe('Prisma model name (e.g. "User", "Order"). If provided, generates a complete repository scaffold.'),
+        fields: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('Field names of the model (e.g. ["id", "email", "name", "createdAt"]). Used with modelName for tailored examples.'),
+    }, async (params) => {
+        let content = repositoryPattern_1.REPOSITORY_PATTERN_KNOWLEDGE;
+        if (params.modelName && params.fields && params.fields.length > 0) {
+            content += '\n\n' + (0, repositoryPattern_1.REPOSITORY_PATTERN_WITH_MODEL)(params.modelName, params.fields);
+        }
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    });
+    // --- get-mapping-pattern ---
+    server.tool('get-mapping-pattern', 'Returns the Archipel mapping pattern — branded type-safe mapping keys, MappingProfileBase, MappingService, and MappingModule registration. Optionally tailored to a specific entity and response class.', {
+        entityName: zod_1.z
+            .string()
+            .optional()
+            .describe('Entity name (e.g. "Product", "User"). If provided, generates tailored mapping scaffold.'),
+        fields: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('Field names of the entity (e.g. ["id", "name", "barcode", "createdAt"]).'),
+        responseName: zod_1.z
+            .string()
+            .optional()
+            .describe('Response class name (e.g. "ProductResponse"). Defaults to "{entityName}Response".'),
+    }, async (params) => {
+        let content = mappingPattern_1.MAPPING_PATTERN_KNOWLEDGE;
+        if (params.entityName && params.fields && params.fields.length > 0) {
+            const responseName = params.responseName || `${params.entityName}Response`;
+            content += '\n\n' + (0, mappingPattern_1.MAPPING_PATTERN_WITH_CONTEXT)(params.entityName, params.fields, responseName);
+        }
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    });
+    // --- get-module-pattern ---
+    server.tool('get-module-pattern', 'Returns the Archipel NestJS dynamic module pattern — register(), port/adapter injection, ConfigModule integration. Optionally tailored with module name and port definitions.', {
+        moduleName: zod_1.z
+            .string()
+            .optional()
+            .describe('Module name (e.g. "NotificationModule"). If provided, generates a complete module scaffold.'),
+        ports: zod_1.z
+            .array(zod_1.z.string())
+            .optional()
+            .describe('Port class names (e.g. ["NotificationPort", "TemplatePort"]). Abstract port classes for dependency inversion.'),
+    }, async (params) => {
+        let content = modulePattern_1.MODULE_PATTERN_KNOWLEDGE;
+        if (params.moduleName && params.ports && params.ports.length > 0) {
+            content += '\n\n' + (0, modulePattern_1.MODULE_PATTERN_WITH_CONTEXT)(params.moduleName, params.ports);
+        }
+        return {
+            content: [{ type: 'text', text: content }],
+        };
+    });
+    // --- get-error-handling-pattern ---
+    server.tool('get-error-handling-pattern', 'Returns the Archipel error handling pattern — domain errors, RepositoryError, exception filters, and structured error response envelopes.', {}, async () => {
+        return {
+            content: [{ type: 'text', text: errorHandlingPattern_1.ERROR_HANDLING_PATTERN_KNOWLEDGE }],
+        };
+    });
+    // --- get-config-pattern ---
+    server.tool('get-config-pattern', 'Returns the Archipel configuration pattern — typed config keys (createConfigKey), ConfigRegistry, ConfigService, env.ts conventions, and ConfigModule integration.', {}, async () => {
+        return {
+            content: [{ type: 'text', text: configPattern_1.CONFIG_PATTERN_KNOWLEDGE }],
+        };
+    });
+    // --- get-guard-pattern ---
+    server.tool('get-guard-pattern', 'Returns the Archipel guard & interceptor pattern — metadata decorators, FeatureGuard, RolesGuard, FeatureUsageInterceptor, and the full decorator-guard-interceptor trio.', {}, async () => {
+        return {
+            content: [{ type: 'text', text: guardPattern_1.GUARD_PATTERN_KNOWLEDGE }],
+        };
+    });
+    // --- get-dto-pattern ---
+    server.tool('get-dto-pattern', 'Returns the Archipel DTO & validation pattern — Request/Response DTOs, class-validator decorators, cross-field validation, query parameter DTOs, OpenAPI integration, and naming conventions.', {}, async () => {
+        return {
+            content: [{ type: 'text', text: dtoPattern_1.DTO_PATTERN_KNOWLEDGE }],
+        };
+    });
+    // --- get-testing-pattern ---
+    server.tool('get-testing-pattern', 'Returns the Archipel testing pattern — Vitest conventions, mocking patterns for repositories/services/delegates, AAA structure, and test naming conventions.', {}, async () => {
+        return {
+            content: [{ type: 'text', text: testingPattern_1.TESTING_PATTERN_KNOWLEDGE }],
+        };
+    });
+}
+// #endregion
+main().catch((error) => {
+    process.stderr.write(`[${SERVER_NAME}] Fatal error: ${String(error)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=main.js.map

package/src/models/IPackageDoc.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Describes a loaded package documentation entry.
+ */
+export interface IPackageDoc {
+    /** Directory name (e.g. "platform-core"). */
+    readonly name: string;
+    /** Human-readable title from frontmatter. */
+    readonly title: string;
+    /** Short description from frontmatter. */
+    readonly description: string;
+    /** Tags from frontmatter. */
+    readonly tags: readonly string[];
+    /** Scoped npm package name (e.g. "@breadstone/archipel-platform-core"). */
+    readonly packageScope: string;
+    /** Markdown body of the hand-written docs (without frontmatter). */
+    readonly content: string;
+    /** Concatenated API reference markdown (from api/ subfolder). */
+    readonly apiContent: string;
+}

package/src/models/IPackageDoc.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=IPackageDoc.js.map