@cdmbase/wiki-browser 12.0.18-alpha.29 → 12.0.18-alpha.31

package/lib/templates/content/content-manifest.json

@@ -33,6 +33,18 @@
       "updatedAt": "Recently",
       "frontmatter": {}
     },
+    {
+      "contentId": "llm-templates_folder_and_codegen_guide",
+      "slug": "templates_folder_and_codegen_guide",
+      "filePath": "/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+      "relativePath": "LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+      "categoryId": "LLM",
+      "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+      "description": "",
+      "author": "Documentation",
+      "updatedAt": "Recently",
+      "frontmatter": {}
+    },
     {
       "contentId": "llm-backend-proxies-services-llm",
       "slug": "backend-proxies-services-llm",
@@ -117,6 +129,18 @@
       "updatedAt": "Recently",
       "frontmatter": {}
     },
+    {
+      "contentId": "llm-mcp-mcp_servers_setup_guide",
+      "slug": "mcp-mcp_servers_setup_guide",
+      "filePath": "/content/docs/LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md",
+      "relativePath": "LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md",
+      "categoryId": "LLM",
+      "title": "MCP_SERVERS_SETUP_GUIDE",
+      "description": "",
+      "author": "Documentation",
+      "updatedAt": "Recently",
+      "frontmatter": {}
+    },
     {
       "contentId": "llm-organization-components-form-llm",
       "slug": "organization-components-form-llm",
@@ -3607,6 +3631,15 @@
           "updatedAt": "Recently",
           "categoryId": "LLM"
         },
+        {
+          "id": "llm-mcp-mcp_servers_setup_guide",
+          "title": "MCP_SERVERS_SETUP_GUIDE",
+          "description": "",
+          "slug": "mcp-mcp_servers_setup_guide",
+          "author": "Documentation",
+          "updatedAt": "Recently",
+          "categoryId": "LLM"
+        },
         {
           "id": "llm-organization-components-form-llm",
           "title": "Organization Components Form Llm",
@@ -3660,6 +3693,15 @@
           "author": "Documentation",
           "updatedAt": "Recently",
           "categoryId": "LLM"
+        },
+        {
+          "id": "llm-templates_folder_and_codegen_guide",
+          "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+          "description": "",
+          "slug": "templates_folder_and_codegen_guide",
+          "author": "Documentation",
+          "updatedAt": "Recently",
+          "categoryId": "LLM"
         }
       ]
     },
@@ -5340,6 +5382,7 @@
   "contentPathMap": {
     "generators-project-generate-fullproject": "/content/docs/Generators/Project/generate-fullproject.md",
     "llm-logger.llm": "/content/docs/LLM/Logger.llm.md",
+    "llm-templates_folder_and_codegen_guide": "/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
     "llm-backend-proxies-services-llm": "/content/docs/LLM/backend-proxies-services-llm.md",
     "llm-backend-service-llm": "/content/docs/LLM/backend-service-llm.md",
     "llm-db_migration_llm": "/content/docs/LLM/db_migration_llm.md",
@@ -5347,6 +5390,7 @@
     "llm-inngest-inngest_function_development_guide_llm": "/content/docs/LLM/inngest/INNGEST_FUNCTION_DEVELOPMENT_GUIDE_LLM.md",
     "llm-inngest-inngest_namespace_llm": "/content/docs/LLM/inngest/INNGEST_NAMESPACE_LLM.md",
     "llm-llm_workflow_namespace": "/content/docs/LLM/llm_workflow_namespace.md",
+    "llm-mcp-mcp_servers_setup_guide": "/content/docs/LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md",
     "llm-organization-components-form-llm": "/content/docs/LLM/organization-components-form-llm.md",
     "llm-page-component-llm": "/content/docs/LLM/page-component-llm.md",
     "llm-preference-roles-and-permissions": "/content/docs/LLM/preference-roles-and-permissions.md",
@@ -8326,6 +8370,28 @@
               }
             ]
           },
+          {
+            "type": "directory",
+            "name": "mcp",
+            "path": "LLM/mcp",
+            "children": [
+              {
+                "type": "file",
+                "name": "MCP_SERVERS_SETUP_GUIDE",
+                "title": "MCP_SERVERS_SETUP_GUIDE",
+                "path": "LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md",
+                "contentId": "llm-mcp-mcp_servers_setup_guide",
+                "slug": "mcp-mcp_servers_setup_guide",
+                "categoryId": "LLM",
+                "filePath": "/content/docs/LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md",
+                "relativePath": "LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md",
+                "description": "",
+                "author": "Documentation",
+                "updatedAt": "Recently",
+                "frontmatter": {}
+              }
+            ]
+          },
           {
             "type": "file",
             "name": "backend-proxies-services-llm",
@@ -8475,6 +8541,21 @@
             "author": "Documentation",
             "updatedAt": "Recently",
             "frontmatter": {}
+          },
+          {
+            "type": "file",
+            "name": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+            "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+            "path": "LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+            "contentId": "llm-templates_folder_and_codegen_guide",
+            "slug": "templates_folder_and_codegen_guide",
+            "categoryId": "LLM",
+            "filePath": "/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+            "relativePath": "LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md",
+            "description": "",
+            "author": "Documentation",
+            "updatedAt": "Recently",
+            "frontmatter": {}
           }
         ]
       },
@@ -10880,6 +10961,19 @@
           ],
           "isFile": false
         },
+        {
+          "title": "Mcp",
+          "path": null,
+          "children": [
+            {
+              "title": "MCP_SERVERS_SETUP_GUIDE",
+              "path": "/help/LLM/mcp-mcp_servers_setup_guide",
+              "children": [],
+              "isFile": true
+            }
+          ],
+          "isFile": false
+        },
         {
           "title": "Backend Proxies Services Llm",
           "path": "/help/LLM/backend-proxies-services-llm",
@@ -10939,6 +11033,12 @@
           "path": "/help/LLM/tailwind-css-llm",
           "children": [],
           "isFile": true
+        },
+        {
+          "title": "TEMPLATES_FOLDER_AND_CODEGEN_GUIDE",
+          "path": "/help/LLM/templates_folder_and_codegen_guide",
+          "children": [],
+          "isFile": true
         }
       ],
       "isFile": false

package/lib/templates/content/docs/LLM/TEMPLATES_FOLDER_AND_CODEGEN_GUIDE.md

@@ -0,0 +1,392 @@
+# Templates Folder Pattern & Code Generation Pipeline
+
+## Overview
+
+The `packages/common/` package in both adminIde-stack and forms-stack is **entirely auto-generated**. You should **NEVER manually edit** files in `packages/common/`. Instead, all service interfaces, repository interfaces, SERVER_TYPES entries, and service-schemas are generated from **templates folders** inside each server module, combined with GraphQL schema codegen.
+
+## The Templates Folder Pattern
+
+### Location
+
+Every server module has a `templates/` folder at:
+
+```
+packages-modules/{module}/server/src/templates/
+```
+
+Or in forms-stack:
+
+```
+packages/{module}/server/src/templates/
+```
+
+### Structure
+
+```
+templates/
+├── constants/
+│   ├── SERVER_TYPES.ts.template     ← Symbol.for() DI tokens for this module
+│   ├── DB_COLL_NAMES.ts.template    ← MongoDB collection names
+│   └── DB_SLUG_NAMES.ts.template    ← (optional) slug name constants
+├── repositories/
+│   └── {EntityName}Repository.ts.template  ← Repository interface (I{EntityName}Repository)
+└── services/
+    ├── {EntityName}Service.ts.template     ← Service interface (I{EntityName}Service)
+    └── {EntityName}DataLoader.ts.template  ← DataLoader interface (optional)
+```
+
+### Template File Format
+
+Template files use `.ts.template` extension but are **plain TypeScript** — NOT Handlebars/EJS. They are authoritative source files that get **copied/merged** into `packages/common/src/` during the `regenerateGraphql` process.
+
+#### Example: SERVER_TYPES.ts.template
+
+```typescript
+// packages-modules/marketplace/server/src/templates/constants/SERVER_TYPES.ts.template
+export const SERVER_TYPES = {
+    IRegistryExtensionService: Symbol.for('IRegistryExtensionService'),
+    IRegistryExtensionRepository: Symbol.for('IRegistryExtensionRepository'),
+    IExtensionContributionService: Symbol.for('IExtensionContributionService'),
+    IExtensionContributesProvider: Symbol.for('IExtensionContributesProvider'),
+};
+```
+
+#### Example: Service Interface Template
+
+```typescript
+// packages-modules/marketplace/server/src/templates/services/ExtensionContributionService.ts.template
+import { IExtensionContributes } from 'common/server'; // ← reuse the generated GraphQL type
+
+export interface IExtensionContributesProvider {
+    getContributes(extensionId: string, version?: string): Promise<IExtensionContributes>;
+}
+
+export interface IExtensionContributionService {
+    registerProvider(sourceCollection: string, provider: IExtensionContributesProvider): void;
+    getContributions(extensionId: string, version?: string): Promise<IExtensionContributes | null>;
+}
+
+declare module '../apollo-context' {
+    interface ServerContext {
+        extensionContributionService: IExtensionContributionService;
+    }
+}
+```
+
+> **Preference: Reuse Generated GraphQL Types**
+>
+> When a type is already defined in the `.graphql` schema and gets generated as a TypeScript type in `generated-models.ts`, the template should **import and reuse** that generated type via `import { ITypeName } from 'common/server'` rather than redefining its own version. This avoids type duplication and keeps a single source of truth for the type shape.
+>
+> See [Reusing Generated GraphQL Types in Templates](#reusing-generated-graphql-types-in-templates) for details.
+
+### What Gets Generated Where
+
+| Template Source                                         | Generated Destination                                              |
+| ------------------------------------------------------- | ------------------------------------------------------------------ |
+| `templates/constants/SERVER_TYPES.ts.template`          | **MERGED** into `packages/common/src/constants/SERVER_TYPES.ts`    |
+| `templates/services/{Entity}Service.ts.template`        | **COPIED** to `packages/common/src/services/{Entity}Service.ts`    |
+| `templates/repositories/{Entity}Repository.ts.template` | **COPIED** to `packages/common/src/services/{Entity}Repository.ts` |
+| `templates/constants/DB_COLL_NAMES.ts.template`         | **MERGED** into `packages/common/src/constants/DB_COLL_NAMES.ts`   |
+| _(barrel exports)_                                      | `packages/common/src/services/index.ts` is **auto-updated**        |
+
+The merged SERVER_TYPES.ts has comments showing which module contributed each block:
+
+```typescript
+// from package: platform-server
+IAccountService: Symbol.for('IAccountService'),
+// from package: marketplace-module-server
+IRegistryExtensionService: Symbol.for('IRegistryExtensionService'),
+```
+
+## Code Generation Pipeline
+
+### Commands
+
+| Command                  | Script                                   | Purpose                                                    |
+| ------------------------ | ---------------------------------------- | ---------------------------------------------------------- |
+| `yarn regenerateGraphql` | `tools/codegenGenerator.mjs`             | Discover schemas + copy templates → generates `codegen.ts` |
+| `yarn generateGraphql`   | `graphql-codegen-esm` (reads codegen.ts) | Generate TypeScript types, Zod schemas, Apollo hooks       |
+| `postgenerateGraphql`    | `lerna run build --scope=common`         | Build the common package (auto-runs after generateGraphql) |
+
+### Step 1: `yarn regenerateGraphql`
+
+Runs `tools/codegenGenerator.mjs` which:
+
+1. Reads `cdecode-config.json` for configuration
+2. Calls `@common-stack/rollup-vite-utils` codegen utilities
+3. **Discovers** all `.graphql` / `.gql` schemas from:
+    - `node_modules/@adminide-stack/*/lib/**/*.graphql` (npm packages)
+    - `packages/*/server/src/**/*.graphql` (local packages)
+4. **Copies all templates/** to `packages/common/src/`:
+    - Merges all `SERVER_TYPES.ts.template` into one `SERVER_TYPES.ts`
+    - Copies service/repository interfaces to `services/`
+    - Updates `services/index.ts` barrel exports
+5. **Generates** `codegen.ts` with resolved schema paths
+
+### Step 2: `yarn generateGraphql`
+
+Runs `graphql-codegen-esm` which reads the generated `codegen.ts` and produces 4 output files in `packages/common/src/generated/`:
+
+| Output File                | Plugin                                                                      | Purpose                                         |
+| -------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------- |
+| `generated-models.ts`      | typescript, typescript-operations, typescript-resolvers, typescript-mongodb | TypeScript interfaces/types from GraphQL schema |
+| `generated-zod-schemas.ts` | `@common-stack/codegen-zod/graphql`                                         | Zod validation schemas from GraphQL types       |
+| `generated.tsx`            | typescript-react-apollo                                                     | React Apollo query/mutation hooks               |
+| `introspection-result.ts`  | fragment-matcher                                                            | Apollo cache fragment matching                  |
+
+After writing all files, two **afterAllFileWrite** hooks run:
+
+1. `node scripts/fix-enum-references.js` — Fixes enum reference issues in generated code
+2. `node node_modules/@common-stack/codegen-zod/dist/service/generateAllServiceSchemas.js` — Generates `service-schemas.ts`
+
+### Step 3: `generateAllServiceSchemas.js`
+
+This script (from `@common-stack/codegen-zod`):
+
+1. Reads `cdecode-config.json` → `serviceSchemas` section:
+    ```json
+    {
+        "serviceSchemas": {
+            "servicesDir": "packages/common/src/services",
+            "outputFile": "packages/common/src/generated/service-schemas.ts",
+            "skipServices": ["AuthBackendClient", "PubSub", ...],
+            "graphqlSchemasPath": "packages/common/src/generated/generated-zod-schemas.ts"
+        }
+    }
+    ```
+2. **Scans** `packages/common/src/services/` for all `.ts` files
+3. **Parses** each file with TypeScript compiler API looking for `export interface I*Service` or `I*Manager`
+4. **Extracts** method signatures (parameter names, types, optionality)
+5. **Cross-references** with `generated-zod-schemas.ts` to find Zod schemas for GraphQL types
+6. **Generates** `service-schemas.ts` with:
+    - A `{ServiceName}Schemas` object per service interface
+    - Zod schemas for each method's parameters
+    - A `topic` property (Moleculer service name)
+    - An aggregated `AllServiceSchemas` export
+
+### Step 4: `postgenerateGraphql`
+
+Automatically runs after `generateGraphql`:
+
+- `lerna run build --scope=common` — Compiles the common package so other packages can use the new types
+
+## Complete Pipeline Diagram
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│  yarn regenerateGraphql                                          │
+│  └─ tools/codegenGenerator.mjs                                   │
+│     └─ reads cdecode-config.json                                 │
+│     └─ calls @common-stack/rollup-vite-utils/codegen             │
+│        ├─ Discovers .graphql/.gql schemas from node_modules +    │
+│        │  local packages                                          │
+│        ├─ Generates codegen.ts with resolved paths               │
+│        ├─ Copies all templates/ → packages/common/src/           │
+│        │  ├─ services/*.ts.template → services/*.ts              │
+│        │  ├─ constants/SERVER_TYPES.ts.template → MERGED into    │
+│        │  │   constants/SERVER_TYPES.ts                           │
+│        │  └─ Updates services/index.ts barrel exports            │
+│        └─ Sets up common package boilerplate                     │
+├─────────────────────────────────────────────────────────────────┤
+│  yarn generateGraphql                                            │
+│  └─ graphql-codegen-esm (reads codegen.ts)                       │
+│     └─ Generates 4 files in packages/common/src/generated/:     │
+│        ├─ generated-models.ts     (TS types from .graphql)       │
+│        ├─ generated-zod-schemas.ts (Zod schemas)                 │
+│        ├─ generated.tsx           (React Apollo hooks)           │
+│        └─ introspection-result.ts (fragment matcher)             │
+│     └─ afterAllFileWrite hooks:                                  │
+│        ├─ fix-enum-references.js                                 │
+│        └─ generateAllServiceSchemas.js                           │
+│           └─ Scans services/ interfaces → generates              │
+│              service-schemas.ts (Zod schemas for Moleculer)      │
+├─────────────────────────────────────────────────────────────────┤
+│  postgenerateGraphql (auto-runs)                                 │
+│  └─ lerna run build --scope=common                               │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## How to Add a New Backend Service
+
+### Step 1: Create the GraphQL Schema
+
+Create a `.graphql` file in the server module:
+
+```
+packages-modules/{module}/server/src/graphql/schemas/{entity}.graphql
+```
+
+Define types, queries, mutations.
+
+### Step 2: Create Template Files
+
+Create template files in the server module's `templates/` folder:
+
+**SERVICE_TYPES entries:**
+
+```
+packages-modules/{module}/server/src/templates/constants/SERVER_TYPES.ts.template
+```
+
+Add Symbol.for() entries for new service/repository/dataloader.
+
+**Service interface:**
+
+```
+packages-modules/{module}/server/src/templates/services/{EntityName}Service.ts.template
+```
+
+Define the `I{EntityName}Service` interface with method signatures.
+
+**Repository interface (if needed):**
+
+```
+packages-modules/{module}/server/src/templates/repositories/{EntityName}Repository.ts.template
+```
+
+### Step 3: Run Code Generation
+
+```bash
+yarn regenerateGraphql   # Discovers schemas + copies templates to common
+yarn generateGraphql      # Generates TS types, Zod schemas, Apollo hooks, service-schemas
+```
+
+After this, `packages/common/` will have:
+
+- Updated `SERVER_TYPES.ts` with new symbols
+- New service interface file in `services/`
+- Updated `services/index.ts` barrel exports
+- Updated `generated-models.ts` with GraphQL types
+- Updated `service-schemas.ts` with Moleculer schemas
+
+### Step 4: Implement the Service
+
+Create the concrete implementation:
+
+```
+packages-modules/{module}/server/src/services/{entity-name}-service.ts
+```
+
+### Step 5: Create Container Module
+
+Bind the service in the container:
+
+```
+packages-modules/{module}/server/src/containers/module.ts
+```
+
+### Step 6: Create Resolver
+
+Create the GraphQL resolver:
+
+```
+packages-modules/{module}/server/src/graphql/resolvers/{entity-name}-resolver.ts
+```
+
+### Step 7: Wire into Feature Module
+
+Update the Feature in:
+
+```
+packages-modules/{module}/server/src/module.ts
+```
+
+## Reusing Generated GraphQL Types in Templates
+
+When writing `.ts.template` files, **always prefer importing types that are already generated from GraphQL schemas** rather than defining duplicate interfaces manually.
+
+### Why
+
+The `yarn generateGraphql` step produces TypeScript types in `packages/common/src/generated/generated-models.ts` for every GraphQL type, query, and mutation. These generated types are the **single source of truth** for the shape of data flowing through the GraphQL layer. If a template redefines the same structure (even with a different name), the two can drift apart when the schema evolves.
+
+### How
+
+Template files are copied into `packages/common/src/services/` — so they can import from `'common/server'` just like any other file in the common package. The generated types are re-exported through `common/server`.
+
+```typescript
+// ✅ CORRECT — import the generated type
+import { IExtensionContributes } from 'common/server';
+
+export interface IExtensionContributesProvider {
+    getContributes(extensionId: string, version?: string): Promise<IExtensionContributes>;
+}
+```
+
+```typescript
+// ❌ WRONG — manually redefining the same shape
+export interface IExtensionContributesResult {
+    uiLayout?: Record<string, unknown>[];
+    configuration?: Record<string, unknown>[];
+    // ... duplicates the GraphQL-generated IExtensionContributes
+}
+
+export interface IExtensionContributesProvider {
+    getContributes(extensionId: string, version?: string): Promise<IExtensionContributesResult>;
+}
+```
+
+### When to Define Your Own Types
+
+Only define a type locally in the template when:
+
+- The type has **no corresponding GraphQL schema definition** (e.g., an internal-only DTO not exposed via the API)
+- The type intentionally **differs** from the GraphQL type (e.g., a partial/extended variant)
+- The type is a **generic utility** interface not tied to a schema entity
+
+### Existing Templates That Import Generated Types
+
+Many existing templates already follow this pattern:
+
+| Template                                   | Imports from `'common/server'`                                                                        |
+| ------------------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `ExtensionGalleryService.ts.template`      | `IGalleryExtension`, `IExtensionManifest`, `IGalleryPager`, `AsDomainType`, `IRegistryExtensionModel` |
+| `ExtensionGalleryDataLoader.ts.template`   | `IGalleryExtension`, `IDataLoader`                                                                    |
+| `InstalledExtensionService.ts.template`    | Multiple model types                                                                                  |
+| `MarketplacePublisherService.ts.template`  | `IMarketplacePublisherModel`, `AsDomainType`                                                          |
+| `ExtensionContributionService.ts.template` | `IExtensionContributes`                                                                               |
+
+### Pipeline Order Consideration
+
+Since `yarn regenerateGraphql` (copies templates) runs **before** `yarn generateGraphql` (generates types), you might wonder: how can a template import a type that hasn't been generated yet?
+
+The answer is that generated types from **previous runs** are already present in `packages/common/src/generated/`. The pipeline is designed to be run incrementally:
+
+1. First run: Define the `.graphql` schema → `generateGraphql` produces the types
+2. Second run (or same session): Create the template that imports those types → `regenerateGraphql` copies the template → `generateGraphql` regenerates (types already exist)
+
+In practice, you always run both commands together, so the generated types are available by the time the common package is compiled.
+
+## Key Rules
+
+1. **NEVER manually edit `packages/common/`** — all files are generated
+2. **ALWAYS create `.ts.template` files** in your module's `templates/` folder for new interfaces
+3. **ALWAYS run `yarn regenerateGraphql`** after creating/modifying template files
+4. **ALWAYS run `yarn generateGraphql`** after creating/modifying `.graphql` schema files
+5. **The `postgenerateGraphql` script runs automatically** — no need to manually build common
+6. **SERVER_TYPES.ts is a merge of ALL modules'** `SERVER_TYPES.ts.template` files
+7. **service-schemas.ts is auto-generated** from service interfaces in `packages/common/src/services/`
+8. **PREFER importing generated GraphQL types** (`import { ITypeName } from 'common/server'`) over redefining the same shape in templates — the GraphQL schema is the single source of truth for API types
+
+## Downstream Stacks (e.g., forms-stack)
+
+Downstream stacks consume upstream npm packages. The flow:
+
+1. Upstream (adminIde-stack) publishes `@adminide-stack/*` packages with compiled `.graphql` schemas in `lib/`
+2. Downstream `codegen.ts` picks up schemas from `node_modules/@adminide-stack/*/lib/**/*.graphql`
+3. Downstream `yarn regenerateGraphql` copies templates from both:
+    - npm packages (upstream templates)
+    - Local packages (downstream-only templates)
+4. This is why downstream common packages have upstream types — they come through the template copy process
+
+### Adding a New Service in Downstream Stack
+
+If the service interface already exists in the upstream npm package:
+
+- Just run `yarn regenerateGraphql` — it will copy the template from `node_modules/`
+- Then run `yarn generateGraphql` — it will pick up `.graphql` schemas from `node_modules/`
+
+If the upstream package hasn't been published yet:
+
+- Define interfaces **locally** in the module (NOT in common)
+- Use `Symbol.for()` for DI tokens to ensure cross-container compatibility
+- Once upstream publishes, run `yarn regenerateGraphql` to get the official templates

package/lib/templates/content/docs/LLM/mcp/MCP_SERVERS_SETUP_GUIDE.md

@@ -0,0 +1,147 @@
+# MCP Servers Setup Guide
+
+Share the pre-configured MCP (Model Context Protocol) servers with your team so every developer gets **Zep memory** and **Neo4j knowledge graph** tools in VS Code Copilot.
+
+---
+
+## What's Included
+
+| Server    | Purpose                              | Tools Provided                                                                                           |
+| --------- | ------------------------------------ | -------------------------------------------------------------------------------------------------------- |
+| **Zep**   | Long-term memory & LLM coding guides | `search_memory`, `get_session_messages`, `get_session_memory`, `list_sessions`, `list_users`, `get_user` |
+| **Neo4j** | Knowledge graph queries              | `cypher_query`, `get_schema`                                                                             |
+
+---
+
+## For the Person Sharing (One-Time)
+
+### Create the Bundle
+
+```bash
+cd ~
+zip -r mcp-servers-bundle.zip \
+  .vscode/mcp-servers/neo4j-mcp/server.mjs \
+  .vscode/mcp-servers/neo4j-mcp/package.json \
+  .vscode/mcp-servers/neo4j-mcp/package-lock.json \
+  .vscode/mcp-servers/zep-mcp/server.mjs \
+  .vscode/mcp-servers/zep-mcp/package.json \
+  .vscode/mcp-servers/zep-mcp/package-lock.json
+```
+
+This produces a **~29 KB** zip (excludes `node_modules/`). Share via Slack, email, or your internal file store.
+
+---
+
+## For Recipients
+
+### Step 1 — Unzip
+
+```bash
+cd ~
+unzip mcp-servers-bundle.zip
+```
+
+This creates:
+
+```
+~/.vscode/mcp-servers/
+├── neo4j-mcp/
+│   ├── server.mjs
+│   ├── package.json
+│   └── package-lock.json
+└── zep-mcp/
+    ├── server.mjs
+    ├── package.json
+    └── package-lock.json
+```
+
+### Step 2 — Install Dependencies
+
+```bash
+cd ~/.vscode/mcp-servers/neo4j-mcp && npm install
+cd ~/.vscode/mcp-servers/zep-mcp && npm install
+```
+
+### Step 3 — Add MCP Configuration
+
+Open (or create) the **global** MCP config file:
+
+| OS          | Path                                               |
+| ----------- | -------------------------------------------------- |
+| **macOS**   | `~/Library/Application Support/Code/User/mcp.json` |
+| **Linux**   | `~/.config/Code/User/mcp.json`                     |
+| **Windows** | `%APPDATA%\Code\User\mcp.json`                     |
+
+Paste the following:
+
+```json
+{
+    "servers": {
+        "neo4j": {
+            "type": "stdio",
+            "command": "node",
+            "args": ["${userHome}/.vscode/mcp-servers/neo4j-mcp/server.mjs"],
+            "env": {
+                "NEO4J_URI": "neo4j+s://neo4j-bolt.cdebase.dev:443",
+                "NEO4J_USERNAME": "neo4j",
+                "NEO4J_PASSWORD": "zepzepzep",
+                "NEO4J_DATABASE": "neo4j"
+            }
+        },
+        "zep": {
+            "type": "stdio",
+            "command": "node",
+            "args": ["${userHome}/.vscode/mcp-servers/zep-mcp/server.mjs"],
+            "env": {
+                "ZEP_API_URL": "https://zep.cdebase.dev",
+                "ZEP_API_KEY": "emVwLXNlY3JldC1rZXktY2hhbmdlLW1lLWluLXByb2R1Y3Rpb24="
+            }
+        }
+    }
+}
+```
+
+> **`${userHome}`** is resolved by VS Code at runtime — no need to hardcode your username.
+
+### Step 4 — Restart VS Code
+
+Reload the window (`Cmd+Shift+P` → "Developer: Reload Window") or restart VS Code entirely.
+
+### Step 5 — Verify
+
+Open Copilot Chat (Agent mode) and ask:
+
+```
+Search Zep memory for "backend service creation guide"
+```
+
+You should see results from the `cdebase-llm-guides` session.
+
+---
+
+## Troubleshooting
+
+### MCP servers not showing up
+
+1. Check the config path is correct for your OS
+2. Ensure `node` is available in your PATH (`node --version`)
+3. Confirm `npm install` completed without errors in both server directories
+
+### "unauthorized" errors from Zep or Neo4j
+
+- The API keys/passwords in the config are for the shared dev environment
+- If credentials have been rotated, get the new values from the team lead
+
+### Servers appear but tools fail
+
+- Restart the MCP server: `Cmd+Shift+P` → "MCP: List Servers" → select the server → "Restart"
+- Check VS Code Output panel → select the MCP server from the dropdown for error logs
+
+---
+
+## Adding More MCP Servers Later
+
+1. Create a new folder under `~/.vscode/mcp-servers/{server-name}/`
+2. Add `server.mjs`, `package.json`, and install dependencies
+3. Add a new entry in `mcp.json` under `"servers"`
+4. Re-zip and redistribute the bundle to the team

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cdmbase/wiki-browser",
-    "version": "12.0.18-alpha.29",
+    "version": "12.0.18-alpha.31",
     "description": "Sample core for higher packages to depend on",
     "license": "ISC",
     "author": "CDMBase LLC",
@@ -65,7 +65,7 @@
             }
         ]
     },
-    "gitHead": "b577e67df67aa6315f66811f794a9fb212c678a3",
+    "gitHead": "0ca551ec8a669f790a8470ff043833da3667a811",
     "typescript": {
         "definition": "lib/index.d.ts"
     }