@node-in-layers/mcp-server 2.3.1 → 2.5.0

package/README.md

@@ -1,149 +1,351 @@
 # MCP Server - A Node In Layers Package for building MCP Servers
 
-This library adds the ability to easily create MCP servers with Node In Layers.
+A Node In Layers package for building MCP servers. It exposes your domains, features, and model CRUDs as MCP tools so an AI can discover and call them. Companion library: `@node-in-layers/mcp-client` (shared protocols for features, models, and tools).
 
-It has a companion library called '@node-in-layers/mcp-client' which is used for creating MCP clients. These two libraries share the same functions for defining models and tools.
+This system is `self-describing` and automatically organizes tools into an optimized and efficient system, that reduces the total number of tools. This system also automatically includes prompting and examples that greatly increase AI tool selection and formatting accuracy in systems, to include in systems with hundreds, if not thousands of tools.
 
-## New Layer
+[API Docs](https://node-in-layers.github.io/mcp-server/)
 
-This library adds a new layer `mcp` to the system. It should be placed after the `express` layer.
+---
 
-## Usage
+## How To Use This
 
-In order to use this library, you must make additions to your config, as well as create and export "mcp" layers from your apps/domains.
+### 1. Install
 
-### Config
-
-you add this app/domain to your config file. You should do this before your apps which will add tools to the MCP server.
+```bash
+npm install @node-in-layers/mcp-server
+```
 
-You then configure the `mcp` app/domain with the following:
+### 2. Configure
 
 ```typescript
-const mcpConfig = {
-  // (optional) The name of your MCP server.
-  name: 'mcp',
-  // (optional) The version of your MCP server.
-  version: '1.0.0',
-  // The server config from @l4t/mcp-ai/simple-server/types.js
-  server: {
-    connection: {
-      type: 'http',
-      host: 'localhost',
-      port: 3000,
-    },
+// /config.base.mts
+import { CoreNamespace } from '@node-in-layers/core'
+import { McpNamespace, HttpConnection } from '@node-in-layers/mcp-server'
+
+export default () => ({
+  systemName: 'your-system-name',
+  [CoreNamespace.root]: {
+    /* 1. Add to the Apps List */
+    apps: await Promise.all([
+      // Other Very Early Modules
+      //import('@node-in-layers/data/index.js'),
+
+      // Insert Here
+      import('@node-in-layers/mcp-server/index.js'),
+
+      // Insert Your Domains Here
+    ]),
+    /* 2. Add mcp layer. NOTE: You must have entries between features and mcp */
+    layerOrder: ['services', 'features', ['entries', 'mcp']], // can also be ['entries', 'express', 'mcp']
   },
-  logging: {
-    // optional
-    // If you want to change the default. Its 'info' by default.
-    requestLogLevel: 'info',
-    // If you want to change the default. Its 'info' by default.
-    responseLogLevel: 'info',
+  /* 3. Add Mcp Server Configurations */
+  [McpNamespace]: {
+    // Required: The configuration of the server itself.
+    server: {
+      connection: {
+        type: 'http',
+        url: 'http://localhost',
+        port: 4000,
+      } as HttpConnection,
+    },
+    // Optional arguments go here.
   },
-}
-
-const config = {
-  ['@node-in-layers/mcp-server']: mcpConfig,
-}
+})
 ```
 
-### Creating an MCP Layer
+### 3. What's Now Available
+
+1. Features are automatically exposed (unless specifically hidden)
+2. Model CRUDS are automatically exposed (unless specifically hidden)
+3. An `mcp` layer is now available to features, and includes additional capabilities in the namespace: `McpNamespace`. (Explained later)
+
+### 4. Run The Server
 
-You can create an MCP layer by exporting a function from your app/domain that returns a layer.
+You can very easily run the server in a simple script by doing the following:
 
 ```typescript
-// /src/yourDomain/mcp.ts
-import { McpContext, McpNamespace } from '@node-in-layers/mcp-server'
-import { Config } from '@node-in-layers/core'
-import { YourFeaturesLayer } from './features.js'
-
-const create = (context: McpContext<Config, YourFeaturesLayer>) => {
-  // Adds your tool.
-  context.mcp[McpNamespace].addTool({
-    name: 'my-hello-world-tool',
-    description: 'My Tool',
-    execute: async (input: any) => {
-      return 'Hello, world!'
-    },
+import { McpNamespace } from '@node-in-layers/mcp-server'
+const system: System = (await core.loadSystem<SystemConfig>({
+  environment,
+})) as any // "System" is your typed System object.
+await system.mcp[McpNamespace].start(context)
+```
+
+#### Example with ./bin/mcp_server.mts file (feel free to copy paste)
+
+```typescript
+#!/usr/bin/env tsx
+
+import esMain from 'es-main'
+import { ArgumentParser } from 'argparse'
+import * as core from '@node-in-layers/core'
+import { McpNamespace } from '@node-in-layers/mcp-server'
+import { SystemConfig } from '../src/types.js'
+import { System } from '../src/system/types.js'
+
+const _parseArguments = () => {
+  const parser = new ArgumentParser({
+    description: 'Starts the MCP server.',
   })
+  parser.add_argument('environment', {
+    help: 'The environment for the service.',
+  })
+  return parser.parse_args()
+}
 
-  // Create a tool from your feature
-  context.mcp[McpNamespace].addTool({
-    name: 'my-hello-world-tool',
-    description: 'My Tool',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        name: {
-          type: 'string',
-        },
-      },
-      required: ['name'],
-    },
-    execute: (input: any) => {
-      // You get an object, pass it back to your feature. Handles async for you.
-      return context.features.yourDomain.yourFeature(input)
-    },
+const startServer = async (environment: string) => {
+  const system = (await core.loadSystem<SystemConfig>({
+    environment,
+  })) as unknown as System
+  if (system.config[McpNamespace].server.connection.type === 'http') {
+    console.info(
+      `Starting MCP server on ${system.config[McpNamespace].server.connection.port}...`
+    )
+  }
+  process.on('SIGINT', async function () {
+    await system.services['@node-in-layers/data'].cleanup()
+    process.exit()
   })
 
-  return {}
+  await system.mcp[McpNamespace].start(system)
 }
 
-export { create }
+if (esMain(import.meta)) {
+  const args = _parseArguments()
+  startServer(args.environment).catch((error: any) => {
+    console.error('Failed to start the server:', error)
+    process.exit(1)
+  })
+}
 ```
 
-### Adding Models
+## Background and How This Works
+
+### MCP interface (domains, features, models)
+
+The MCP tool surface is **organized by domain, then features and models**:
+
+- **Domains** — The AI can list domains (`list_domains`), then for each domain list features (`list_features`) and (if present) list models. Only domains that have features or models exposed will be shown.
+- **Features** — For a given domain/feature, the AI can get the schema (`describe_feature`) and run it (`execute_feature`).
+- **Models** — For a given domain/model, the AI can get the schema and run save, retrieve, delete, search, bulkInsert, bulkDelete.
+
+The **documentation returned to the AI** (including what START_HERE returns) is **configurable**. By default the server provides instructions so the AI will:
+
+1. List domains.
+2. List features (and models) within a domain.
+3. Describe a feature or model when it needs the schema.
+4. Execute features and model CRUD operations with the right arguments.
+
+So the AI learns the shape of the system from the configurable “start here” and default system entries, then uses the tools to list/describe/execute as needed.
 
-You can wrap your models with CRUDS functions and add them to the MCP server with the mcp layer.
-NOTE: In order for this to work your layer must have both a services and a features layer. (In addition to your models.) Node in layers will automatically create a cruds property for you with your models, and you can add them.
+### Hiding components
 
-Here is an example of doing it one at a time. (Not generally recommended, but doable).
+You can restrict what is visible (as well as executable) to callers (e.g. certain domains, features, or all model CRUDs) so only the intended surface is exposed.
+
+Configure `hideComponents` under the MCP config:
+
+- **paths** — Dot-separated paths to hide, e.g. `myDomain`, `myDomain.myFeature`, `myDomain.cruds`, `myDomain.cruds.MyModel`.
+- **domains** — Domain names to hide entirely (they won’t appear in `list_domains`).
+- **allModels** — If `true`, no model CRUD tools are exposed.
+
+Everything not hidden remains available. See [Configuration details](#configuration-details) for the full shape.
+
+Example (partial config):
 
 ```typescript
-// /src/yourDomain/mcp.ts
-import { McpContext, McpNamespace } from '@node-in-layers/mcp-server'
-import { Config } from '@node-in-layers/core'
-import { YourFeaturesLayer } from './features.js'
-
-const create = (context: McpContext<Config, YourFeaturesLayer>) => {
-  // Adds your models cruds through features.
-  context.mcp[McpNamespace].addModelCruds(
-    context.features.yourFeature.cruds.Cars
-  )
-
-  return {}
-}
+// /config.base.mts
+import { McpNamespace } from '@node-in-layers/mcp-server'
+
+export default () => ({
+  // ...
+  [McpNamespace]: {
+    // ...
+    hideComponents: {
+      // Completely hide these domains from the MCP surface
+      domains: ['internalAdmin', 'experimental'],
+
+      // Hide specific paths (domains, features, or models)
+      paths: [
+        'billing.cruds', // hide all models in the billing domain
+        'users.cruds.ApiKeys', // hide a single model. (The ApiKeys table located in the users domain)
+        'debug.internalFeature', // hide a specific feature
+      ],
+
+      // Or hide all models everywhere. Good for "feature" oriented systems.
+      allModels: false, // set true to hide all model CRUD tools
+    },
+  },
+})
 ```
 
-Here is a way that you can really cook with gas. (Highly recommended)
+---
 
-```typescript
-// /src/yourDomain/mcp.ts
-import { McpContext, McpNamespace, mcpModels } from '@node-in-layers/mcp-server'
-import { Config } from '@node-in-layers/core'
-import { YourFeaturesLayer } from './features.js'
+## System description
 
-const create = (context: McpContext<Config, YourFeaturesLayer>) => {
-  // This automatically adds ALL of your models from features.
-  mcpModels('yourDomain')(context)
+Under `systemDescription` you set **static metadata** for your system that is included in the start-here response:
 
-  return {}
-}
+- **description** — Short system description for the AI.
+- **version** — System version string.
+
+This is the right place for “what this system is” and version; it does not control which tools exist or what the START_HERE tool includes (that is under `startHere`).
+
+Example (partial config):
+
+```typescript
+// /config.base.mts
+import { McpNamespace } from '@node-in-layers/mcp-server'
+
+export default () => ({
+  // ...
+  [McpNamespace]: {
+    // ...
+    systemDescription: {
+      description: 'Order management and billing system for ACME Corp.',
+      version: '2.3.0',
+    },
+  },
+})
 ```
 
-Another way to organize adding models is from a centralized mcp domain. Put this as your very last domain after all your other domains have been loaded.
+---
+
+## Start here
+
+The **START_HERE** tool is what makes the system navigable: the AI is instructed to call it first (or when the user asks for help). Its response is built from:
+
+1. **System metadata** — `systemName`, `systemDescription`, `systemVersion` from config.
+2. **Default system entries** — Built-in docs (e.g. “this is a domain-layered system”, “MCP navigation workflow”, “cross-layer props”). You can turn these off with `startHere.hideDefaultSystemEntries`.
+3. **Optional: include domains / include features** — If `startHere.includeDomains` is true, the response includes the current list of domains (as if `list_domains` had been called). If `startHere.includeFeatures` is true, it also includes the list of features per domain (as if `list_features` had been called for each). So the AI gets domains and/or features **without** making extra tool calls.
+4. **Examples of use** — Custom entries you add under `startHere.examplesOfUse`. These are where you document **higher-level flows** (e.g. “run feature A, then B, then C”). The built-in docs explain domains, features, and models; they do **not** explain your app-specific sequences. Put those in `examplesOfUse`, as **JSON object examples with minimal prose** so the AI can apply them directly.
+
+**Include domains / include features**  
+Enabling these is like pre-running `list_domains` and/or `list_features` and embedding the result in START_HERE. The downside is **context size**: for large systems (many tools), that can consume a lot of context and add noise. For **small systems (on the order of 1–10 tools)** it’s usually fine. For larger systems, prefer **examples of use** and let the AI call `list_domains` / `list_features` when needed.
+
+Example (partial config):
+
+````typescript
+// /config.base.mts
+import { McpNamespace } from '@node-in-layers/mcp-server'
+
+export default () => ({
+  // ...
+  [McpNamespace]: {
+    // ...
+    startHere: {
+      // Optional: override tool identity
+      name: 'START_HERE',
+      description:
+        'BEFORE YOU DO ANYTHING, call this first to learn how to navigate the system.',
+
+      // What to include in the start-here response
+      hideDefaultSystemEntries: false, // do we want the ones that come by default? Usually this is yes.
+      includeDomains: true, // Should we go ahead and tell it the domains? Commonly this should be true.
+      includeFeatures: false, // Should we tell them all the features on the first go? In most cases this should be FALSE. Unless its a small system with few functions.
+
+      // Higher-level flows through your system
+      examplesOfUse: [
+        {
+          name: 'Create order then fetch it',
+          description: 'Typical flow that creates an order and then retrieves it.',
+          // Giving ACTUAL examples (json data, + small annotations) works amazingly.
+          example: `
+```markdown
+// 1. Create an order
+{ "tool": "execute_feature", "args": { "domain": "orders", "featureName": "createOrder" } }
+// 2. Get the order by id (using the id from step 1)
+{ "tool": "execute_feature", "args": { "domain": "orders", "featureName": "getOrderById" } }
+````
+
+          `,
+          tags: ['orders', 'flow'],
+        },
+      ],
+    },
+
+},
+})
+
+````
+
+---
+
+## Extending with custom tools
+
+You can add your own MCP tools via the MCP layer using `addTool`. Use this from a layer that has access to `mcp[McpNamespace]` (e.g. after the MCP layer in the stack).
+
+Example (conceptual):
 
 ```typescript
-// /src/mcp/mcp.ts
-import { McpContext, McpNamespace, mcpModels } from '@node-in-layers/mcp-server'
-import { Config } from '@node-in-layers/core'
-
-const create = (context: McpContext<Config>) => {
-  // Add all your models for your whole system in one go.
-  mcpModels('yourDomain')(context)
-  mcpModels('yourDomain2')(context)
-  mcpModels('yourDomain3')(context)
-  mcpModels('yourDomain4')(context)
-
-  return {}
-}
+// In a layer that runs after the MCP layer and has context.mcp[McpNamespace]
+const mcp = context.mcp[McpNamespace]
+mcp.addTool({
+  name: 'my_custom_tool',
+  description: 'Does something custom',
+  inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+  outputSchema: { type: 'object' },
+  execute: async (input) => ({ result: input.id }),
+})
+````
+
+Your tool is then exposed alongside the built-in domain/feature/model tools.
+
+---
+
+## How to run the server
+
+- **start** — Start the MCP server (listens on the connection defined in config).  
+  `mcp[McpNamespace].start(systemContext, options?)`
+- **getApp** — Get the Express app (for HTTP/SSE) so you can mount it in your own server.  
+  `mcp[McpNamespace].getApp(options?)`
+
+Use **start** when the MCP server is the main process. Use **getApp** when you compose with an existing Express app (e.g. mount the MCP app at a path).
+
+---
+
+## Middleware and routes
+
+- **addPreRouteMiddleware(middleware)** — Add Express middleware that runs before MCP route handling.
+- **addAdditionalRoute(route)** — Register an extra Express route (e.g. health or admin) on the same app.
+
+Call these during setup (e.g. from a layer that has access to `mcp[McpNamespace]`) before the server is started or the app is used.
+
+---
+
+## Changing logging configuration
+
+Logging is configured under the `logging` section of the MCP config. You can control log levels and optionally add structured data to each request/response log entry.
+
+- **requestLogLevel** / **responseLogLevel**: Override the default log level (`info`) for incoming requests and outgoing responses.
+- **requestLogGetData(input)**: Function that maps the raw request input into extra data to log.
+- **responseLogGetData(result)**: Function that maps the raw tool result into extra data to log.
+
+Example (partial config):
+
+```typescript
+// /config.base.mts
+import { McpNamespace } from '@node-in-layers/mcp-server'
+
+export default () => ({
+  // ...
+  [McpNamespace]: {
+    // ...
+    logging: {
+      // Adjust verbosity
+      requestLogLevel: 'debug',
+      responseLogLevel: 'info',
+
+      // Attach additional request information to the log.
+      requestLogGetData: (input: Request) => ({
+        something: input.something,
+      }),
+      responseLogGetData: (input: Request) => ({
+        // Shape this to your needs; example:
+        truncated: true,
+      }),
+    },
+  },
+})
 ```
+
+---

package/docs/node-in-layers-system.json

@@ -1,9 +1,9 @@
 [
     {
         "id": "2e19b8bf-2a4f-4f3c-9b7e-0f10c9e55c01",
-        "name": "What is a Node-In-Layers (NIL) system?",
+        "name": "This is a domain layered system.",
         "tags": ["intro", "layers", "models"],
-        "details": "A Node-In-Layers (NIL) system organizes application code into cohesive apps and layered responsibilities. Key default layers: globals (shared config and infra), services (talk to the outside world: DBs, APIs, files), features (business flows orchestrating steps), and entries (starting points like REST, CLI, serverless). Models are first-class: they define validated data structures and, when configured with an ORM, expose CRUDS APIs across services and features. This document focuses on how to navigate and use a NIL system via the MCP server tools."
+        "details": "This system is a series of features that are organized into cohesive domains. Each domain can also export CRUDS access to models, if it chooses to. Domains can be listed, features can be listed, described and called, and so can models."
     },
     {
         "id": "7c0c9643-92f4-4603-984d-3a25b9bd3a28",
@@ -80,7 +80,7 @@
         "id": "a0a1c3cf-7f3f-4e4b-9f1e-2b1a9a7b11aa",
         "name": "list_domains",
         "tags": ["mcp", "nil", "discovery"],
-        "details": "Lists domains available in the system (from NIL features context). Hidden domains are omitted by server policy.",
+        "details": "Lists domains shows the domains available for access.",
         "example": {
             "request": {
                 "tool": "list_domains",
@@ -99,7 +99,7 @@
         "id": "f3b7b0d1-0d4e-4a25-9c76-8a7ef0f2d3c2",
         "name": "list_features",
         "tags": ["mcp", "nil", "discovery", "features"],
-        "details": "Lists callable business features for a domain. Use before execute_feature to see options.",
+        "details": "Lists callable business features for a domain. Use before execute_feature to get the exact input schema for a feature.",
         "example": {
             "request": {
                 "tool": "list_features",
@@ -121,7 +121,7 @@
         "id": "3f2f4a9a-4d75-41f0-b1a9-3b7f5a223c17",
         "name": "describe_feature",
         "tags": ["mcp", "nil", "schema", "features"],
-        "details": "Returns an OpenAPI-like schema for a feature. If the feature is NIL-annotated, the full schema is derived; otherwise, a generic schema is produced.",
+        "details": "Returns an OpenAPI-like schema for a feature.",
         "example": {
             "request": {
                 "tool": "describe_feature",
@@ -311,5 +311,11 @@
         "example": {
             "markdown": "User asks: \"Reserve 1 unit of ABC-123 if available.\"\n\n1. list_domains {}\n   - Choose domain = inventory.\n2. list_features { domain: \"inventory\" } and list_models { domain: \"inventory\" }\n   - See feature reserveItem and model Inventories.\n3. describe_feature { domain: \"inventory\", featureName: \"checkItemAvailability\" }\n   - Confirm args: { sku: string, quantity: number }.\n4. execute_feature { domain: \"inventory\", featureName: \"checkItemAvailability\", args: { sku: \"ABC-123\", quantity: 1 }, crossLayerProps: { logging: { ids: [{ aiSessionId: \"8c2ab...\" }, { aiRequestId: \"f4c7a...\" }] } } }\n   - If available: true -> proceed.\n5. execute_feature { domain: \"inventory\", featureName: \"reserveItem\", args: { sku: \"ABC-123\", quantity: 1, userId: \"u-42\" }, crossLayerProps: { logging: { ids: [{ aiSessionId: \"8c2ab...\" }, { aiRequestId: \"f4c7a...\" }] } } }\n   - Returns reservationId.\n"
         }
+    },
+    {
+        "id": "0a1b2c3d-4e5f-4607-8a90-b1c2d3e4f507",
+        "name": "Working with the user",
+        "tags": ["user", "interaction"],
+        "details": "Unless the user asks for it don't explain Domain/Models of the system to the user. The features are the primary thing the user cares about, and only to the extent that YOU the AI call them. The details about what goes in them, only matters for them to run other features first. Knowing how to call and navigate this interface is YOUR (the AI)'s job."
     }
 ]

package/internal-libs.d.ts

@@ -0,0 +1,29 @@
+import { Logger } from '@node-in-layers/core';
+import { z, ZodType } from 'zod';
+import { AuthInfo, RequestInfo } from './types.js';
+/**
+ * Converts the MCP SDK's RequestHandlerExtra into our local RequestInfo.
+ * The SDK only provides HTTP headers; all other fields default to empty values
+ * since they are not available through the SDK transport layer.
+ */
+export declare const buildRequestInfoFromSdkExtra: (extra?: any) => RequestInfo;
+/**
+ * Extracts AuthInfo from the MCP SDK's RequestHandlerExtra.authInfo, if present.
+ */
+export declare const buildAuthInfoFromSdkExtra: (extra?: any) => AuthInfo | undefined;
+/**
+ * Merges crossLayerProps from all sources and returns a cleaned input object
+ * with a canonical mergedCrossLayerProps.
+ *
+ * Sources merged (in order):
+ * 1. input.crossLayerProps — client-provided CLP at the top level of tool args
+ * 2. input.args.crossLayerProps — CLP nested inside args (used by features)
+ * 3. { requestInfo, authInfo } — from the MCP SDK transport's extra
+ * 4. logger IDs — appended via createCrossLayerProps
+ */
+export declare const buildMergedToolInput: (input: any, extra: any, logger: Logger) => {
+    mergedInput: any;
+    mergedCrossLayerProps: any;
+};
+export declare const openApiToZodSchema: (parameters: any) => Record<string, ZodType>;
+export declare const isZodSchema: (schema: any) => schema is z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;