@openziti/ziti-mcp-server 0.1.0

package/dist/utils/tools.js

@@ -0,0 +1,149 @@
+import { log } from './logger.js';
+import { Glob } from './glob.js';
+/**
+ * Filters the provided tools collection based on specified glob patterns and readOnly flag.
+ * This function processes the input patterns against available tools to determine
+ * which tools should be returned. It handles special cases like wildcard patterns,
+ * empty pattern arrays, and pattern matching errors. When readOnly is true,
+ * it only returns tools that have _meta.readOnly set to true or tools that follow read-only patterns.
+ *
+ * IMPORTANT: The readOnly flag takes priority over pattern matching for security reasons.
+ * Even if patterns match non-read-only tools, when readOnly=true is specified,
+ * only read-only tools will be returned.
+ *
+ * @param allTools - Complete collection of available tools to be filtered
+ * @param patterns - Optional glob patterns to filter tools by (e.g., 'ziti*', 'jwt-*')
+ *                   If omitted or empty, all tools will be returned
+ *                   A single '*' pattern will return all tools
+ * @param readOnly - Optional flag to only return read-only tools
+ *                   When true, only returns tools marked as readOnly
+ *                   Takes priority over pattern matching for security
+ * @returns Array of Tool objects that match the specified criteria
+ *          Returns all tools if no patterns provided or on error
+ *
+ * @example
+ * // Return all tools that start with "auth"
+ * const authTools = getAvailableTools(tools, ['auth*']);
+ *
+ * @example
+ * // Return all read-only tools (regardless of pattern matching)
+ * const readOnlyTools = getAvailableTools(tools, ['*'], true);
+ *
+ * @example
+ * // Return only read-only tools that match the pattern
+ * // Note: --read-only takes priority, so even if the pattern matches non-read-only tools,
+ * // only the read-only ones will be returned
+ * const readOnlyAuthTools = getAvailableTools(tools, ['ziti_*_application'], true);
+ */
+export function getAvailableTools(allTools, patterns, readOnly) {
+    // Start with all tools
+    let filteredTools = allTools;
+    // Apply pattern filtering if patterns are provided
+    if (patterns?.length) {
+        filteredTools = filterToolsByPatterns(filteredTools, patterns);
+    }
+    // Apply read-only filtering if requested
+    // IMPORTANT: This is applied AFTER pattern filtering, ensuring that
+    // --read-only takes priority over --tools for security
+    // Even if non-read-only tools match the pattern, they will be filtered out here
+    if (readOnly) {
+        filteredTools = filterToolsByReadOnly(filteredTools);
+    }
+    return filteredTools;
+}
+function filterToolsByPatterns(tools, patterns) {
+    try {
+        // Special case for global wildcard
+        if (patterns.length === 1 && patterns[0] === '*') {
+            return tools; // Keep all tools, no pattern filtering needed
+        }
+        // Compile glob patterns once for performance
+        const globs = patterns.map((pattern) => new Glob(pattern));
+        // Track matching tools and matches per pattern
+        const enabledToolNames = new Set();
+        const matchesByPattern = new Map();
+        // For each tool, check if it matches any pattern
+        for (const tool of tools) {
+            for (const glob of globs) {
+                if (glob.matches(tool.name)) {
+                    enabledToolNames.add(tool.name);
+                    // Count matches per pattern for logging
+                    const patternString = glob.toString();
+                    matchesByPattern.set(patternString, (matchesByPattern.get(patternString) || 0) + 1);
+                    // Once we find a match, no need to check other patterns
+                    break;
+                }
+            }
+        }
+        // Log match counts for wildcard patterns for debugging
+        for (const [pattern, count] of matchesByPattern.entries()) {
+            if (pattern.includes('*')) {
+                log(`Glob pattern '${pattern}' matched ${count} tools`);
+            }
+        }
+        // Create the filtered tool list based on patterns
+        const filteredTools = tools.filter((tool) => enabledToolNames.has(tool.name));
+        log(`Selected ${filteredTools.length} available tools based on patterns`);
+        return filteredTools;
+    }
+    catch (error) {
+        // Log error and use all tools as fallback
+        log(`Error determining available tools: ${error instanceof Error ? error.message : String(error)}`);
+        return tools;
+    }
+}
+function filterToolsByReadOnly(tools) {
+    const readOnlyTools = tools.filter((tool) => tool._meta?.readOnly === true);
+    log(`Filtered to ${readOnlyTools.length} read-only tools`);
+    return readOnlyTools;
+}
+/**
+ * Validates tool patterns against available tools to ensure each pattern matches at least one tool.
+ * This function verifies that each provided pattern (including glob patterns) corresponds to
+ * at least one available tool, throwing specific errors for different validation scenarios.
+ *
+ * @param patterns - Array of tool name patterns to validate
+ *                   Can include glob patterns with wildcards (e.g., 'ziti*')
+ *                   Empty array or undefined will skip validation
+ * @param availableTools - Collection of Tool objects to validate patterns against
+ *
+ * @throws {Error} If availableTools is not a valid array or is empty
+ * @throws {Error} If any pattern doesn't match at least one tool name, with different
+ *                 error messages for exact matches vs. wildcard patterns
+ *
+ * @example
+ * // Validate specific tool names
+ * validatePatterns(['ziti-jwt', 'ziti-management'], tools);
+ *
+ * @example
+ * // Validate with glob patterns
+ * validatePatterns(['ziti*', 'jwt-*'], tools);
+ *
+ * @see {@link Glob} for the pattern matching implementation
+ * @see {@link getAvailableTools} for filtering tools using these patterns
+ */
+export function validatePatterns(patterns, availableTools) {
+    // Skip validation if patterns array is empty
+    if (!patterns || patterns.length === 0) {
+        return;
+    }
+    // Input validation
+    if (!availableTools || !Array.isArray(availableTools)) {
+        throw new Error('Invalid tools array provided for validation');
+    }
+    if (availableTools.length === 0) {
+        throw new Error('No tools available for pattern validation');
+    }
+    // Extract tool names for faster matching
+    const toolNames = availableTools.map((tool) => tool.name);
+    // Validate each pattern
+    for (const pattern of patterns) {
+        const glob = new Glob(pattern);
+        const matchesAnyTool = toolNames.some((name) => glob.matches(name));
+        if (!matchesAnyTool) {
+            const errorPrefix = pattern.includes('*') ? `No tools match the pattern` : `Invalid tool`;
+            throw new Error(`${errorPrefix}: ${pattern}. Accepted tools are: ${toolNames.join(', ')}`);
+        }
+    }
+}
+//# sourceMappingURL=tools.js.map

package/dist/utils/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../../src/utils/tools.ts"],"names":[],"mappings":"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"}

package/dist/utils/types.d.ts

@@ -0,0 +1,55 @@
+export interface ToolAnnotations {
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+    readOnlyHint?: boolean;
+    title?: string;
+}
+export interface Tool {
+    name: string;
+    description: string;
+    inputSchema?: Record<string, any>;
+    _meta?: {
+        requiredScopes: string[];
+        readOnly?: boolean;
+    };
+    annotations?: ToolAnnotations;
+}
+export interface HandlerRequest {
+    token: string;
+    parameters: Record<string, any>;
+}
+export interface HandlerConfig {
+    zitiControllerHost: string;
+    domain: string | undefined;
+}
+export interface HandlerResponse {
+    content: Array<{
+        type: string;
+        [key: string]: any;
+    }>;
+    isError: boolean;
+}
+export interface ClientOptions {
+    tools: string[];
+    readOnly?: boolean;
+}
+export interface OpenZitiApplication {
+    client_id: string;
+    name: string;
+    [key: string]: any;
+}
+export interface OpenZitiResourceServer {
+    id: string;
+    name: string;
+    identifier: string;
+    [key: string]: any;
+}
+export interface OpenZitiPaginatedResponse {
+    clients?: OpenZitiApplication[];
+    resource_servers?: OpenZitiResourceServer[];
+    total?: number;
+    page?: number;
+    per_page?: number;
+    [key: string]: any;
+}

package/dist/utils/types.js

@@ -0,0 +1,3 @@
+// This file contains common types and interfaces used across the application.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/utils/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/utils/types.ts"],"names":[],"mappings":"AAAA,8EAA8E"}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@openziti/ziti-mcp-server",
+  "version": "0.1.0",
+  "description": "OpenZiti Model Context Protocol (MCP) Server — A secure implementation of an MCP server that provides AI assistants with controlled access to the OpenZiti Controller's Management API through natural language. It enables AI-assisted Ziti Network management while enforcing best practices around security, least-privilege access, and zero-trust.",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "ziti-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "package.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "prebuild": "npm run format | grep -vF '(unchanged)' && npm run lint",
+    "build": "rm -rf dist && tsc",
+    "build-controller-client-2": "rm -rf ./src/utils/controller-client && npx @hey-api/openapi-ts -i management.yml -o ./src/utils/controller-client",
+    "build-controller-client": "rm -rf ./src/utils/controller-client && npx @hey-api/openapi-ts",
+    "postbuild": "shx chmod +x dist/*.js",
+    "dev": "tsx src/index.ts run",
+    "dev:debug": "DEBUG=ziti-mcp tsx src/index.ts run",
+    "dev:inspect": "npx @modelcontextprotocol/inspector tsx src/index.ts run",
+    "start": "node dist/index.js run",
+    "start:debug": "DEBUG=ziti-mcp node dist/index.js run",
+    "start:inspect": "npx @modelcontextprotocol/inspector node dist/index.js run",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "setup": "node utils/local-setup.js",
+    "notice": "node utils/generate-notice.js",
+    "lint": "eslint . --ext .js,.ts",
+    "lint:fix": "eslint . --ext .js,.ts --fix",
+    "format": "prettier --write \"**/*.{js,ts,json,md}\"",
+    "format:check": "prettier --check \"**/*.{js,ts,json,md}\"",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "ziti",
+    "openziti",
+    "ai",
+    "mcp",
+    "model context protocol",
+    "claude"
+  ],
+  "author": "NetFoundry",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.2",
+    "auth0": "^4.21.0",
+    "chalk": "^5.4.1",
+    "commander": "^13.1.0",
+    "debug": "^4.4.0",
+    "jwt-decode": "^4.0.0",
+    "keytar": "^7.9.0",
+    "open": "^10.1.0",
+    "which": "^5.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.23.0",
+    "@hey-api/openapi-ts": "^0.87.4",
+    "@types/debug": "^4.1.12",
+    "@types/node": "^22.14.0",
+    "@vitest/coverage-v8": "^3.1.1",
+    "@vitest/ui": "^3.1.1",
+    "eslint": "9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^16.0.0",
+    "msw": "^2.7.3",
+    "prettier": "^3.6.2",
+    "shx": "^0.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2",
+    "typescript-eslint": "^8.29.0",
+    "vitest": "^3.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openziti/openziti-mcp-server.git"
+  },
+  "homepage": "https://github.com/openziti/openziti-mcp-server#readme",
+  "publishConfig": {
+    "access": "public"
+  }
+}