feat: add mcp server to expose SDK_CONTEXT file

nx.json

@@ -367,6 +367,22 @@
       ],
       "cache": true
     },
+    "expose-resources": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "copy:resources"
+      },
+      "dependsOn": [
+        "compile"
+      ],
+      "inputs": [
+        "{projectRoot}/resources/**"
+      ],
+      "outputs": [
+        "{projectRoot}/dist/resources/**"
+      ],
+      "cache": true
+    },
     "expose-schemas": {
       "executor": "nx:run-script",
       "options": {

packages/@ama-mcp/sdk/README.md

@@ -0,0 +1,124 @@
+# @ama-mcp/sdk
+
+MCP module to expose `SDK_CONTEXT.md` from installed packages to AI assistants.
+
+## Purpose
+
+When SDKs are generated using [@ama-sdk/schematics](https://www.npmjs.com/package/@ama-sdk/schematics), they can include an `SDK_CONTEXT.md` file that describes:
+- Available API domains and operations
+- Models used by each domain
+- Guidelines for AI tools to avoid hallucinations
+
+This MCP module automatically discovers and loads these context files from installed packages using Node.js's module resolution, then exposes them to AI assistants.
+
+## Configuration
+
+### VS Code `.vscode/mcp.json`
+
+Configure SDK packages directly in your `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "sdk-context": {
+      "command": "npx",
+      "args": ["ama-mcp-sdk", "--packages", "@my-scope/my-sdk-package", "@other-scope/other-sdk"]
+    }
+  }
+}
+```
+
+## Usage
+
+### CLI (for mcp.json)
+
+```bash
+# Specify packages with --packages flag
+ama-mcp-sdk --packages @my-scope/my-sdk @other-scope/other-sdk
+
+# Show help
+ama-mcp-sdk --help
+```
+
+### Programmatic (in custom MCP server)
+
+```typescript
+import { registerSdkContextToolAndResources } from '@ama-mcp/sdk';
+
+// With explicit packages
+await registerSdkContextToolAndResources(server, {
+  sdkPackages: ['@my-scope/my-sdk']
+});
+
+// Or reads from package.json sdkContext.packages automatically
+await registerSdkContextToolAndResources(server);
+```
+
+### Available Tool
+
+**`get_sdk_context`** - Retrieve SDK context for configured packages
+
+```
+// List all configured SDKs with context
+get_sdk_context()
+
+// Get context for specific package
+get_sdk_context({ packageName: "@my-scope/my-sdk-package" })
+```
+
+### Available Resources
+
+**`sdk-context://instructions`** - Usage guidelines for AI assistants
+
+This resource provides instructions on how to use SDK context effectively to avoid hallucinations when implementing features. AI assistants should read this resource before using the `get_sdk_context` tool.
+
+**`sdk-context://<package-name>`** - SDK context for each configured package
+
+Each configured SDK package that has an `SDK_CONTEXT.md` file is exposed as a resource.
+
+## How It Works
+
+1. Reads `sdkContext.packages` from project's `package.json` or uses CLI arguments
+2. Uses Node.js `require.resolve()` to automatically locate packages
+3. Loads `SDK_CONTEXT.md` from each resolved package
+4. Registers each as an MCP resource
+5. Provides a tool for AI assistants to query SDK information
+
+## Package Resolution
+
+The SDK automatically discovers packages using Node.js's `require.resolve()`. This means:
+
+- **No manual path configuration needed** - packages are found automatically
+- **Works with workspaces** - supports npm/yarn/pnpm workspace configurations
+- **Flexible installation** - works with local, global, or custom module paths
+- **Error handling** - clear error messages when packages aren't found
+
+If a package isn't found, ensure:
+1. The package is installed (`npm install <package-name>`)
+2. The package name is spelled correctly
+3. The package has an `SDK_CONTEXT.md` file in its root
+
+**Security**: The system validates package names to prevent path traversal attacks and only accepts valid npm package name patterns.
+
+## Troubleshooting
+
+### Package Not Found
+```
+Package "@my-scope/my-sdk" not found. Is it installed?
+```
+**Solution**: Install the package or verify the name in your configuration.
+
+### No SDK_CONTEXT.md Found
+```
+No SDK_CONTEXT.md found for @my-scope/my-sdk
+```
+**Solution**: Generate the context file using the command below.
+
+## Generating SDK Context
+
+SDK maintainers can generate `SDK_CONTEXT.md` using:
+
+```bash
+cd /path/to/sdk-project
+npx amasdk-update-sdk-context --interactive
+```

packages/@ama-mcp/sdk/eslint.config.mjs

@@ -0,0 +1,7 @@
+import shared from '../../../eslint.shared.config.mjs';
+import local from './eslint.local.config.mjs';
+
+export default [
+  ...shared,
+  ...local
+];

packages/@ama-mcp/sdk/eslint.local.config.mjs

@@ -0,0 +1,28 @@
+import {
+  dirname,
+} from 'node:path';
+import {
+  fileURLToPath,
+} from 'node:url';
+import globals from 'globals';
+
+const __filename = fileURLToPath(import.meta.url);
+// __dirname is not defined in ES module scope
+const __dirname = dirname(__filename);
+
+export default [
+  {
+    name: '@ama-mcp/sdk/projects',
+    languageOptions: {
+      sourceType: 'module',
+      parserOptions: {
+        tsconfigRootDir: __dirname,
+        projectService: true
+      },
+      globals: {
+        ...globals.node,
+        NodeJS: true
+      }
+    }
+  }
+];

packages/@ama-mcp/sdk/jest.config.js

@@ -0,0 +1,9 @@
+const { getJestProjectConfig } = require('@o3r/test-helpers');
+
+/** @type {import('ts-jest/dist/types').JestConfigWithTsJest} */
+module.exports = {
+  ...getJestProjectConfig(),
+  projects: [
+    '<rootDir>/testing/jest.config.ut.js'
+  ]
+};

packages/@ama-mcp/sdk/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@ama-mcp/sdk",
+  "version": "0.0.0-placeholder",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Experimental package -- MCP module to expose SDK_CONTEXT.md from installed packages to AI assistants",
+  "keywords": [
+    "mcp",
+    "sdk",
+    "ai-context",
+    "otter-module"
+  ],
+  "sideEffects": false,
+  "bin": {
+    "ama-mcp-sdk": "./dist/src/cli.js"
+  },
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    }
+  },
+  "scripts": {
+    "nx": "nx",
+    "ng": "yarn nx",
+    "build": "yarn nx build ama-mcp-sdk",
+    "compile": "tsc -b ./tsconfig.build.json && yarn cpy package.json dist && patch-package-json-main",
+    "copy:resources": "yarn cpy resources dist"
+  },
+  "dependencies": {
+    "@ama-mcp/core": "workspace:~",
+    "@modelcontextprotocol/sdk": "~1.27.0",
+    "@o3r/telemetry": "workspace:~",
+    "commander": "^14.0.0",
+    "tslib": "^2.6.2",
+    "zod": "~4.3.0"
+  },
+  "devDependencies": {
+    "@ama-mcp/core": "workspace:~",
+    "@eslint-community/eslint-plugin-eslint-comments": "^4.4.0",
+    "@modelcontextprotocol/sdk": "~1.27.0",
+    "@nx/eslint": "~22.5.3",
+    "@nx/eslint-plugin": "~22.5.3",
+    "@nx/jest": "~22.5.3",
+    "@nx/js": "~22.5.3",
+    "@o3r/build-helpers": "workspace:^",
+    "@o3r/eslint-config": "workspace:^",
+    "@o3r/eslint-plugin": "workspace:^",
+    "@o3r/test-helpers": "workspace:^",
+    "@stylistic/eslint-plugin": "~5.7.0",
+    "@types/jest": "~30.0.0",
+    "@types/node": "~24.12.0",
+    "@typescript-eslint/parser": "~8.54.0",
+    "cpy-cli": "^6.0.0",
+    "eslint": "~9.39.0",
+    "eslint-import-resolver-node": "~0.3.9",
+    "eslint-import-resolver-typescript": "~4.4.0",
+    "eslint-plugin-import": "~2.32.0",
+    "eslint-plugin-import-newlines": "~1.4.0",
+    "eslint-plugin-jest": "~29.12.0",
+    "eslint-plugin-jsdoc": "~61.7.0",
+    "eslint-plugin-prefer-arrow": "~1.2.3",
+    "eslint-plugin-unicorn": "~62.0.0",
+    "eslint-plugin-unused-imports": "~4.3.0",
+    "globals": "^16.0.0",
+    "jest": "~30.2.0",
+    "jest-junit": "~16.0.0",
+    "jsonc-eslint-parser": "~2.4.0",
+    "ts-jest": "~29.4.0",
+    "typescript": "~5.9.2",
+    "typescript-eslint": "~8.54.0",
+    "zod": "~4.3.0"
+  },
+  "engines": {
+    "node": "^22.17.0 || ^24.0.0"
+  }
+}

packages/@ama-mcp/sdk/project.json

@@ -0,0 +1,25 @@
+{
+  "name": "ama-mcp-sdk",
+  "$schema": "https://raw.githubusercontent.com/nrwl/nx/master/packages/nx/schemas/project-schema.json",
+  "projectType": "library",
+  "sourceRoot": "packages/@ama-mcp/sdk/src",
+  "prefix": "o3r",
+  "targets": {
+    "build": {
+      "executor": "nx:noop",
+      "dependsOn": ["compile", "expose-templates", "expose-resources"]
+    },
+    "compile": {
+      "executor": "nx:run-script",
+      "options": {
+        "script": "compile"
+      }
+    },
+    "expose-resources": {},
+    "test": {},
+    "lint": {},
+    "prepare-publish": {},
+    "publish": {}
+  },
+  "tags": []
+}

packages/@ama-mcp/sdk/resources/INSTRUCTIONS.md

@@ -0,0 +1,40 @@
+# SDK Context Usage Instructions
+
+When implementing features that use installed SDKs, use the `get_sdk_context` tool as your primary source of truth. The SDK context provides a structured methodology for understanding available operations, models, and their organization.
+
+> **Note**: The SDKs available through this MCP server are those explicitly configured in the server launch parameters (via `--packages` arguments or `sdkContext.packages` in `package.json`). Only these SDKs will have context available through the `get_sdk_context` tool.
+
+## Core Principle
+
+**Let the SDK context guide your implementation.** The context document describes the SDK's structure, available operations, and models. Base your responses on what you discover in the context rather than making assumptions.
+
+## Using the SDK Context
+
+1. **Query available SDK contexts** using `get_sdk_context` without arguments to discover configured SDKs
+2. **Retrieve the relevant SDK context** by calling `get_sdk_context` with the package name
+3. **Study the context's structure and methodology** - each SDK context describes how its operations and models are organized
+4. **Follow the patterns provided** - use the exact operation IDs, model imports, and domain organization as documented in the context
+
+## Fallback Discovery
+
+If the SDK context is unavailable or incomplete for a specific operation:
+
+- Search for OpenAPI/Swagger specification files (e.g., `openapi.yaml`, `swagger.json`, `spec.yaml`) in the project
+- Browse the SDK's source files to discover available API classes and methods
+- Check the SDK's `package.json` for entry points or documentation references
+
+## Key Principles
+
+- **Ground your responses in the context** - only use operations, models, and paths that exist in the SDK context or specification
+- **Respect the SDK's organization** - follow the domain structure and naming conventions provided
+- **Avoid assumptions** - if something is not documented in the context, verify its existence before using it
+
+## Troubleshooting
+
+### No SDK contexts found
+
+Ensure the SDK packages are:
+1. Listed in `package.json` under `sdkContext.packages`
+2. Or provided via CLI arguments: `--packages @scope/sdk-name`
+3. Installed in node_modules
+4. Have `SDK_CONTEXT.md` generated (use `amasdk-update-sdk-context` in the SDK project)