@sidurijs/hands 1.0.0

package/dist/mcp-integration.test.js

@@ -0,0 +1,235 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const inMemory_js_1 = require("@modelcontextprotocol/sdk/inMemory.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const core_1 = require("@sidurijs/core");
+const index_1 = require("./index");
+describe('Hands Organ - Full MCP Protocol Integration Suite', () => {
+    const secretKey = 'test_mcp_hands_secret';
+    let engine;
+    let sampleContext;
+    beforeEach(() => {
+        engine = new core_1.ActionPolicyEngine({
+            secretKey,
+            defaultRiskLevel: 'LOW',
+        });
+        sampleContext = {
+            companionId: 'comp-mcp-1',
+            actor: {
+                actorId: 'user-mcp-1',
+                sessionId: 'sess-mcp-1',
+                authorizationRole: 'operator',
+                capabilities: ['tool:mcp_server/echo', 'tool:mcp_server/calculator', 'tool:failing_tool', 'tool:slow_tool'],
+                authenticated: true,
+            },
+            conversation: {
+                channel: 'direct',
+                correlationId: 'corr-mcp-1',
+            },
+        };
+    });
+    test('dynamically discovers tools from an MCP server over transport', async () => {
+        const server = new index_js_1.Server({ name: 'test-mcp-srv', version: '1.0.0' }, { capabilities: { tools: {} } });
+        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'echo',
+                    description: 'Echoes back the message',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            message: { type: 'string' },
+                        },
+                        required: ['message'],
+                    },
+                },
+                {
+                    name: 'calculator',
+                    description: 'Adds two numbers',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            a: { type: 'number' },
+                            b: { type: 'number' },
+                        },
+                        required: ['a', 'b'],
+                    },
+                },
+            ],
+        }));
+        const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+        await server.connect(serverTransport);
+        const hands = new index_1.DefaultHandsOrgan({
+            secretKey,
+            providers: [
+                {
+                    serverName: 'mcp_server',
+                    transport: clientTransport,
+                },
+            ],
+        });
+        const tools = await hands.listTools();
+        expect(tools.length).toBe(2);
+        expect(tools.map((t) => t.name)).toEqual(expect.arrayContaining(['echo', 'calculator']));
+        expect(tools.find((t) => t.name === 'echo')?.providerId).toBe('mcp_server');
+        await hands.close();
+        await server.close();
+    });
+    test('executes MCP tool call with cryptographic authorization and parameter validation', async () => {
+        const server = new index_js_1.Server({ name: 'calc-srv', version: '1.0.0' }, { capabilities: { tools: {} } });
+        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'calculator',
+                    description: 'Adds two numbers',
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            a: { type: 'number' },
+                            b: { type: 'number' },
+                        },
+                        required: ['a', 'b'],
+                    },
+                },
+            ],
+        }));
+        server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+            const args = request.params.arguments;
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ sum: args.a + args.b }),
+                    },
+                ],
+            };
+        });
+        const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+        await server.connect(serverTransport);
+        const hands = new index_1.DefaultHandsOrgan({
+            secretKey,
+            providers: [
+                {
+                    serverName: 'mcp_server',
+                    transport: clientTransport,
+                },
+            ],
+        });
+        // Discover tools and register in policy engine
+        const tools = await hands.listTools();
+        for (const tool of tools) {
+            engine.registerToolDefinition(tool);
+        }
+        // 1. Authorize action
+        const action = {
+            actionId: 'act-calc-101',
+            toolName: 'mcp_server/calculator',
+            parameters: { a: 15, b: 27 },
+            context: sampleContext,
+        };
+        const { capability } = await engine.evaluateAction(action);
+        expect(capability).toBeDefined();
+        // 2. Execute action through hands organ
+        const executionResult = await hands.executeAction(action, capability);
+        expect(executionResult.success).toBe(true);
+        expect(executionResult.lifecycle).toBe('COMPLETED');
+        expect(executionResult.result.content[0].text).toBe(JSON.stringify({ sum: 42 }));
+        await hands.close();
+        await server.close();
+    });
+    test('propagates MCP tool errors properly as execution failures', async () => {
+        const server = new index_js_1.Server({ name: 'err-srv', version: '1.0.0' }, { capabilities: { tools: {} } });
+        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'failing_tool',
+                    description: 'Fails intentionally',
+                    inputSchema: { type: 'object' },
+                },
+            ],
+        }));
+        server.setRequestHandler(types_js_1.CallToolRequestSchema, async () => {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'Database connection failed inside MCP server' }],
+            };
+        });
+        const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+        await server.connect(serverTransport);
+        const hands = new index_1.DefaultHandsOrgan({
+            secretKey,
+            providers: [
+                {
+                    serverName: 'mcp_err',
+                    transport: clientTransport,
+                },
+            ],
+        });
+        const tools = await hands.listTools();
+        for (const tool of tools) {
+            engine.registerToolDefinition(tool);
+        }
+        const action = {
+            actionId: 'act-err-1',
+            toolName: 'mcp_err/failing_tool',
+            parameters: {},
+            context: sampleContext,
+        };
+        const { capability } = await engine.evaluateAction(action);
+        const result = await hands.executeAction(action, capability);
+        expect(result.success).toBe(false);
+        expect(result.lifecycle).toBe('FAILED');
+        expect(result.error).toContain('Database connection failed inside MCP server');
+        await hands.close();
+        await server.close();
+    });
+    test('aborts and handles cancellation of in-flight MCP calls', async () => {
+        const server = new index_js_1.Server({ name: 'slow-srv', version: '1.0.0' }, { capabilities: { tools: {} } });
+        server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+            tools: [
+                {
+                    name: 'slow_tool',
+                    description: 'Takes long to run',
+                    inputSchema: { type: 'object' },
+                },
+            ],
+        }));
+        let timer;
+        server.setRequestHandler(types_js_1.CallToolRequestSchema, async () => {
+            return new Promise((resolve) => {
+                timer = setTimeout(() => resolve({ content: [{ type: 'text', text: 'done' }] }), 200);
+            });
+        });
+        const [clientTransport, serverTransport] = inMemory_js_1.InMemoryTransport.createLinkedPair();
+        await server.connect(serverTransport);
+        const hands = new index_1.DefaultHandsOrgan({
+            secretKey,
+            providers: [
+                {
+                    serverName: 'mcp_slow',
+                    transport: clientTransport,
+                },
+            ],
+        });
+        const tools = await hands.listTools();
+        for (const tool of tools) {
+            engine.registerToolDefinition(tool);
+        }
+        const action = {
+            actionId: 'act-abort-1',
+            toolName: 'mcp_slow/slow_tool',
+            parameters: {},
+            context: sampleContext,
+        };
+        const { capability } = await engine.evaluateAction(action);
+        const controller = new AbortController();
+        setTimeout(() => controller.abort(), 20);
+        const result = await hands.executeAction(action, capability, { signal: controller.signal });
+        clearTimeout(timer);
+        expect(result.success).toBe(false);
+        expect(['CANCELLED', 'TIMED_OUT', 'FAILED']).toContain(result.lifecycle);
+        await hands.close();
+        await server.close();
+    });
+});

package/dist/mcp-provider.d.ts

@@ -0,0 +1,33 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { ToolDefinition } from '@sidurijs/core';
+export interface MCPProviderConfig {
+    serverName: string;
+    baseUrl?: string;
+    command?: string;
+    args?: string[];
+    env?: Record<string, string>;
+    tools?: Array<{
+        definition: ToolDefinition;
+        execute: (parameters: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
+    }>;
+    transport?: Transport;
+    defaultTimeoutMs?: number;
+}
+export interface MCPToolHandler {
+    definition: ToolDefinition;
+    execute: (parameters: Record<string, unknown>, signal?: AbortSignal) => Promise<unknown>;
+}
+export declare class MCPClientProvider {
+    readonly config: MCPProviderConfig;
+    private client?;
+    private connected;
+    private connectingPromise?;
+    constructor(config: MCPProviderConfig);
+    get serverName(): string;
+    isConnected(): boolean;
+    getClient(): Client | undefined;
+    connect(): Promise<void>;
+    discoverTools(): Promise<MCPToolHandler[]>;
+    disconnect(): Promise<void>;
+}

package/dist/mcp-provider.js

@@ -0,0 +1,131 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPClientProvider = void 0;
+const index_js_1 = require("@modelcontextprotocol/sdk/client/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/client/stdio.js");
+const sse_js_1 = require("@modelcontextprotocol/sdk/client/sse.js");
+class MCPClientProvider {
+    config;
+    client;
+    connected = false;
+    connectingPromise;
+    constructor(config) {
+        this.config = config;
+    }
+    get serverName() {
+        return this.config.serverName;
+    }
+    isConnected() {
+        return this.connected && !!this.client;
+    }
+    getClient() {
+        return this.client;
+    }
+    async connect() {
+        if (this.connected) {
+            return;
+        }
+        if (this.connectingPromise) {
+            return this.connectingPromise;
+        }
+        this.connectingPromise = (async () => {
+            let transport = this.config.transport;
+            if (!transport) {
+                if (this.config.command) {
+                    transport = new stdio_js_1.StdioClientTransport({
+                        command: this.config.command,
+                        args: this.config.args,
+                        env: this.config.env,
+                    });
+                }
+                else if (this.config.baseUrl) {
+                    transport = new sse_js_1.SSEClientTransport(new URL(this.config.baseUrl));
+                }
+            }
+            if (!transport) {
+                // In-memory or static tools provider (no remote transport configured)
+                this.connected = true;
+                return;
+            }
+            const client = new index_js_1.Client({
+                name: `siduri-x-${this.config.serverName}`,
+                version: '1.0.0',
+            }, {
+                capabilities: {},
+            });
+            await client.connect(transport);
+            this.client = client;
+            this.connected = true;
+        })();
+        try {
+            await this.connectingPromise;
+        }
+        finally {
+            this.connectingPromise = undefined;
+        }
+    }
+    async discoverTools() {
+        const handlers = [];
+        // 1. If static tools are provided in config, include them
+        if (this.config.tools) {
+            for (const tool of this.config.tools) {
+                handlers.push({
+                    definition: {
+                        ...tool.definition,
+                        providerId: this.config.serverName,
+                    },
+                    execute: tool.execute,
+                });
+            }
+        }
+        // 2. If remote client is configured or connectable, discover tools dynamically via MCP
+        if (this.config.command || this.config.baseUrl || this.config.transport) {
+            if (!this.connected) {
+                await this.connect();
+            }
+            if (this.client) {
+                const response = await this.client.listTools();
+                for (const remoteTool of response.tools) {
+                    const definition = {
+                        name: remoteTool.name,
+                        description: remoteTool.description || '',
+                        inputSchema: remoteTool.inputSchema || { type: 'object' },
+                        providerId: this.config.serverName,
+                        timeoutMs: this.config.defaultTimeoutMs,
+                    };
+                    const execute = async (parameters, signal) => {
+                        if (!this.client) {
+                            throw new Error(`MCP Provider "${this.config.serverName}" is not connected`);
+                        }
+                        const result = await this.client.callTool({
+                            name: remoteTool.name,
+                            arguments: parameters,
+                        }, undefined, { signal });
+                        if (result.isError) {
+                            const errorMessage = Array.isArray(result.content)
+                                ? result.content.map((c) => ('text' in c ? c.text : JSON.stringify(c))).join('\n')
+                                : 'Tool execution returned error status';
+                            throw new Error(errorMessage);
+                        }
+                        return result;
+                    };
+                    handlers.push({ definition, execute });
+                }
+            }
+        }
+        return handlers;
+    }
+    async disconnect() {
+        if (this.client) {
+            try {
+                await this.client.close();
+            }
+            catch {
+                // Ignore close errors during cleanup
+            }
+            this.client = undefined;
+        }
+        this.connected = false;
+    }
+}
+exports.MCPClientProvider = MCPClientProvider;

package/dist/schema-validator.d.ts

@@ -0,0 +1,5 @@
+export interface SchemaValidationResult {
+    valid: boolean;
+    errors: string[];
+}
+export declare function validateInputSchema(schema: Record<string, unknown> | undefined, params: Record<string, unknown> | undefined, currentPath?: string): SchemaValidationResult;

package/dist/schema-validator.js

@@ -0,0 +1,138 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateInputSchema = validateInputSchema;
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+function sanitizeAndCheckForbiddenKeys(val, path = '') {
+    const errors = [];
+    if (val && typeof val === 'object') {
+        if (Array.isArray(val)) {
+            for (let i = 0; i < val.length; i++) {
+                errors.push(...sanitizeAndCheckForbiddenKeys(val[i], `${path}[${i}]`));
+            }
+        }
+        else {
+            const rec = val;
+            // Check own properties and symbol/special names
+            const ownKeys = Object.getOwnPropertyNames(rec);
+            for (const key of ownKeys) {
+                if (FORBIDDEN_KEYS.has(key)) {
+                    errors.push(`Forbidden prototype pollution key "${key}" detected at path "${path ? path + '.' + key : key}"`);
+                }
+                errors.push(...sanitizeAndCheckForbiddenKeys(rec[key], path ? `${path}.${key}` : key));
+            }
+            // Check constructor or prototype property references
+            if (Object.prototype.hasOwnProperty.call(rec, 'constructor')) {
+                errors.push(`Forbidden prototype pollution key "constructor" detected at path "${path ? path + '.constructor' : 'constructor'}"`);
+            }
+            if (Object.prototype.hasOwnProperty.call(rec, '__proto__')) {
+                errors.push(`Forbidden prototype pollution key "__proto__" detected at path "${path ? path + '.__proto__' : '__proto__'}"`);
+            }
+            if (Object.prototype.hasOwnProperty.call(rec, 'prototype')) {
+                errors.push(`Forbidden prototype pollution key "prototype" detected at path "${path ? path + '.prototype' : 'prototype'}"`);
+            }
+        }
+    }
+    return errors;
+}
+function validateInputSchema(schema, params, currentPath = '') {
+    // Always inspect for prototype pollution keys recursively
+    const forbiddenKeyErrors = sanitizeAndCheckForbiddenKeys(params, currentPath);
+    if (forbiddenKeyErrors.length > 0) {
+        return { valid: false, errors: forbiddenKeyErrors };
+    }
+    if (!schema || Object.keys(schema).length === 0) {
+        return { valid: true, errors: [] };
+    }
+    const errors = [];
+    const parameters = params ?? {};
+    // Check type of parameters
+    if (typeof parameters !== 'object' || parameters === null || Array.isArray(parameters)) {
+        return { valid: false, errors: [`Parameter at "${currentPath || 'root'}" must be a JSON object`] };
+    }
+    // 1. Required fields
+    if (Array.isArray(schema.required)) {
+        for (const reqField of schema.required) {
+            if (typeof reqField === 'string') {
+                if (parameters[reqField] === undefined || parameters[reqField] === null) {
+                    const fieldPath = currentPath ? `${currentPath}.${reqField}` : reqField;
+                    errors.push(`Missing required parameter "${fieldPath}"`);
+                }
+            }
+        }
+    }
+    // 2. Recursive properties type checking
+    const properties = schema.properties;
+    if (properties && typeof properties === 'object') {
+        for (const [propName, propSchema] of Object.entries(properties)) {
+            const fieldPath = currentPath ? `${currentPath}.${propName}` : propName;
+            const val = parameters[propName];
+            if (val !== undefined && val !== null && propSchema && typeof propSchema === 'object') {
+                const expectedType = propSchema.type;
+                if (expectedType) {
+                    if (expectedType === 'string' && typeof val !== 'string') {
+                        errors.push(`Parameter "${fieldPath}" expected type string, got ${typeof val}`);
+                    }
+                    else if (expectedType === 'number' && (typeof val !== 'number' || isNaN(val))) {
+                        errors.push(`Parameter "${fieldPath}" expected type number, got ${typeof val}`);
+                    }
+                    else if (expectedType === 'boolean' && typeof val !== 'boolean') {
+                        errors.push(`Parameter "${fieldPath}" expected type boolean, got ${typeof val}`);
+                    }
+                    else if (expectedType === 'array') {
+                        if (!Array.isArray(val)) {
+                            errors.push(`Parameter "${fieldPath}" expected type array, got ${typeof val}`);
+                        }
+                        else if (propSchema.items && typeof propSchema.items === 'object') {
+                            // Recursive array item validation
+                            for (let i = 0; i < val.length; i++) {
+                                const itemPath = `${fieldPath}[${i}]`;
+                                const itemVal = val[i];
+                                const itemType = propSchema.items.type;
+                                if (itemType === 'object' || (propSchema.items.properties && typeof itemVal === 'object')) {
+                                    const nestedRes = validateInputSchema(propSchema.items, itemVal, itemPath);
+                                    if (!nestedRes.valid) {
+                                        errors.push(...nestedRes.errors);
+                                    }
+                                }
+                                else if (itemType && typeof itemVal !== itemType) {
+                                    errors.push(`Parameter "${itemPath}" expected type ${itemType}, got ${typeof itemVal}`);
+                                }
+                            }
+                        }
+                    }
+                    else if (expectedType === 'object') {
+                        if (typeof val !== 'object' || Array.isArray(val)) {
+                            errors.push(`Parameter "${fieldPath}" expected type object, got ${typeof val}`);
+                        }
+                        else {
+                            // Recursive nested object validation
+                            const nestedRes = validateInputSchema(propSchema, val, fieldPath);
+                            if (!nestedRes.valid) {
+                                errors.push(...nestedRes.errors);
+                            }
+                        }
+                    }
+                }
+                // Enum checking
+                if (Array.isArray(propSchema.enum)) {
+                    if (!propSchema.enum.includes(val)) {
+                        errors.push(`Parameter "${fieldPath}" has invalid value "${val}". Must be one of: [${propSchema.enum.join(', ')}]`);
+                    }
+                }
+            }
+        }
+        // additionalProperties restriction
+        if (schema.additionalProperties === false) {
+            for (const key of Object.keys(parameters)) {
+                if (!properties[key]) {
+                    const extraPath = currentPath ? `${currentPath}.${key}` : key;
+                    errors.push(`Unexpected additional parameter "${extraPath}"`);
+                }
+            }
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}

package/organ-manifest.json

@@ -0,0 +1,56 @@
+{
+  "name": "@sidurijs/hands",
+  "organType": "hands",
+  "version": "1.0.0",
+  "displayName": "Hands (MCP Tool Execution)",
+  "description": "Model Context Protocol tool management and cryptographically authorized action execution",
+  "entrypoint": "./dist/index.js",
+  "factory": "DefaultHandsOrgan",
+  "configKey": "hands",
+  "configSchema": {
+    "type": "object",
+    "properties": {
+      "defaultTimeoutMs": {
+        "type": "number",
+        "default": 10000
+      },
+      "providers": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "required": [
+            "serverName"
+          ],
+          "properties": {
+            "serverName": {
+              "type": "string"
+            },
+            "baseUrl": {
+              "type": "string"
+            },
+            "command": {
+              "type": "string"
+            },
+            "args": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        }
+      }
+    }
+  },
+  "environment": [
+    {
+      "name": "ACTION_POLICY_SECRET",
+      "required": false,
+      "secret": true,
+      "description": "HMAC secret key for signing and verifying action execution capabilities (required in production)"
+    }
+  ],
+  "services": [],
+  "database": null,
+  "healthCheck": "probeHandsHealth"
+}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@sidurijs/hands",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc -w",
+    "test": "jest --config jest.config.json"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@sidurijs/core": "workspace:*"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^26.5.1",
+    "jest": "^30.5.1",
+    "ts-jest": "^29.4.12",
+    "typescript": "^5.9.3"
+  },
+  "description": "Hands organ for tool execution, action policy enforcement, and MCP provider integration",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/vxnus-studio/siduri-x",
+    "directory": "packages/organs/hands"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.16.0"
+  },
+  "files": [
+    "dist",
+    "organ-manifest.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./organ-manifest.json": "./organ-manifest.json"
+  }
+}