@slbdn/mcp-tester 1.0.2 → 1.2.0

package/dist/utils/masking.js

@@ -0,0 +1,171 @@
+/**
+ * Secret masking utility for preventing sensitive data from appearing in logs.
+ *
+ * Automatically detects and masks common secret patterns like API keys,
+ * tokens, passwords, and connection strings. Also masks values of known
+ * sensitive environment variable keys.
+ *
+ * @example
+ * ```typescript
+ * import { maskSecrets, addSecretPattern } from '@slbdn/mcp-tester';
+ *
+ * // Built-in patterns are applied automatically
+ * maskSecrets('API key: sk-abc123def456ghi789');
+ * // → 'API key: sk-ab...789'
+ *
+ * // Add custom patterns
+ * addSecretPattern(/my-secret-key-[a-zA-Z0-9]+/g, 'MyOrg API key');
+ * ```
+ */
+/**
+ * Environment variable keys that commonly contain secrets.
+ * Values for these keys will be masked in log output.
+ */
+const SENSITIVE_ENV_KEYS = new Set([
+    'API_KEY',
+    'API_SECRET',
+    'SECRET_KEY',
+    'SECRET',
+    'PRIVATE_KEY',
+    'ACCESS_KEY',
+    'ACCESS_TOKEN',
+    'ACCESS_SECRET',
+    'AUTH_TOKEN',
+    'AUTHORIZATION',
+    'BEARER_TOKEN',
+    'TOKEN',
+    'REFRESH_TOKEN',
+    'SESSION_TOKEN',
+    'SESSION_ID',
+    'ID_TOKEN',
+    'PASSWORD',
+    'PASSWD',
+    'DB_PASSWORD',
+    'DATABASE_PASSWORD',
+    'REDIS_PASSWORD',
+    'MONGO_PASSWORD',
+    'DATABASE_URL',
+    'DB_URL',
+    'MONGODB_URI',
+    'POSTGRES_URL',
+    'MYSQL_URL',
+    'REDIS_URL',
+    'AWS_ACCESS_KEY_ID',
+    'AWS_SECRET_ACCESS_KEY',
+    'AWS_SESSION_TOKEN',
+    'AZURE_CLIENT_SECRET',
+    'GCP_API_KEY',
+    'GOOGLE_API_KEY',
+    'OPENAI_API_KEY',
+    'ANTHROPIC_API_KEY',
+    'GITHUB_TOKEN',
+    'GITLAB_TOKEN',
+    'NPM_TOKEN',
+    'NPM_AUTH_TOKEN',
+    'SLACK_TOKEN',
+    'SLACK_WEBHOOK',
+    'SENTRY_DSN',
+    'ENCRYPTION_KEY',
+    'SIGNING_KEY',
+    'JWT_SECRET',
+    'CSRF_SECRET',
+    'APP_SECRET',
+]);
+const OPENAI_KEY_REGEX = /\bsk-(?:proj|ant)-[a-zA-Z0-9_-]{10,}/g;
+const SK_KEY_REGEX = /\bsk-[a-zA-Z0-9]{12,}/g;
+const AWS_KEY_REGEX = /\bAKIA[A-Z0-9]{16}\b/g;
+const BEARER_REGEX = /\bBearer\s+[a-zA-Z0-9._-]{8,}/gi;
+const JWT_REGEX = /\beyJ[a-zA-Z0-9_-]{10,}/g;
+const HEX_REGEX = /\b[a-f0-9]{40,}\b/g;
+const URL_CREDS_REGEX = /:[a-zA-Z0-9._-]{4,}@[a-zA-Z0-9.-]+/g;
+const KV_REGEX = /\b(?:password|passwd|secret|token|key|auth|credential)s?\s*[:=]\s*["']?[a-zA-Z0-9._/@+-]{8,}["']?/gi;
+/**
+ * Built-in secret patterns that are automatically masked.
+ */
+const DEFAULT_SECRET_PATTERNS = [
+    { pattern: OPENAI_KEY_REGEX, name: 'OpenAI/Anthropic API key' },
+    { pattern: SK_KEY_REGEX, name: 'API key (sk-)' },
+    { pattern: AWS_KEY_REGEX, name: 'AWS access key' },
+    { pattern: BEARER_REGEX, name: 'Bearer token' },
+    { pattern: JWT_REGEX, name: 'JWT token' },
+    { pattern: HEX_REGEX, name: 'Hex token' },
+    { pattern: URL_CREDS_REGEX, name: 'URL credentials' },
+    { pattern: KV_REGEX, name: 'Key-value secret' },
+];
+/** Active secret patterns (built-in + user-added). */
+let activePatterns = [...DEFAULT_SECRET_PATTERNS];
+/** Number of characters to keep visible at start/end when masking. */
+const VISIBLE_CHARS = 3;
+/**
+ * Mask a string value, keeping the first few and last few characters visible
+ * and replacing the rest with `...`.
+ *
+ * @param value - The secret value to mask
+ * @param visibleChars - How many characters to keep visible at start and end
+ * @returns Masked string like "sk-ab...789"
+ */
+export function maskValue(value, visibleChars = VISIBLE_CHARS) {
+    if (visibleChars <= 0 || value.length <= visibleChars * 2 + 3) {
+        return '***';
+    }
+    const start = value.slice(0, visibleChars);
+    const end = value.slice(-visibleChars);
+    return `${start}...${end}`;
+}
+/**
+ * Mask secrets in a string by applying all active secret patterns
+ * and masking values of known sensitive environment variable keys.
+ *
+ * @param input - The value to mask (any type — converted to string)
+ * @returns String with secrets replaced by masked versions
+ */
+export function maskSecrets(input) {
+    if (input === null || input === undefined) {
+        return String(input);
+    }
+    let result = String(input);
+    // 1. First mask values of known sensitive environment variable keys
+    //    Matches: KEY=value, KEY="value", KEY: value, KEY: "value"
+    result = result.replace(/\b([A-Z_][A-Z0-9_]{2,})(\s*[:=]\s*)(["']?)([^\s"']{4,})\3/g, (_match, key, separator, quote, _value) => {
+        if (SENSITIVE_ENV_KEYS.has(key.toUpperCase())) {
+            return `${key}${separator}${quote}***${quote}`;
+        }
+        return _match;
+    });
+    // 2. Then apply built-in and user-added secret patterns
+    for (const { pattern } of activePatterns) {
+        // Create fresh regex to avoid lastIndex issues from global flag
+        const regex = new RegExp(pattern.source, pattern.flags);
+        result = result.replace(regex, (match) => maskValue(match));
+    }
+    return result;
+}
+/**
+ * Add a custom secret pattern to the masking rules.
+ *
+ * @param pattern - Regex pattern to match secrets
+ * @param name - Human-readable name for the pattern
+ */
+export function addSecretPattern(pattern, name = 'custom') {
+    activePatterns.push({ pattern, name });
+}
+/**
+ * Reset all secret patterns to the built-in defaults.
+ * Removes any patterns added via `addSecretPattern()`.
+ */
+export function resetSecretPatterns() {
+    activePatterns = [...DEFAULT_SECRET_PATTERNS];
+}
+/**
+ * Get the list of currently active secret patterns.
+ */
+export function getSecretPatterns() {
+    return [...activePatterns];
+}
+/**
+ * Get the set of sensitive environment variable key names.
+ */
+export function getSensitiveEnvKeys() {
+    return SENSITIVE_ENV_KEYS;
+}
+//# sourceMappingURL=masking.js.map

package/dist/utils/masking.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@slbdn/mcp-tester",
-  "version": "1.0.2",
+  "version": "1.2.0",
   "description": "Minimal MCP client implementation for CI/CD testing of MCP servers",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,38 +9,63 @@
   "files": [
     "dist/client",
     "dist/utils",
+    "dist/cli",
     "dist/index.js",
     "dist/index.d.ts",
     "dist/index.d.ts.map",
     "dist/index.js.map",
+    "dist/assert.js",
+    "dist/assert.d.ts",
+    "dist/assert.d.ts.map",
+    "dist/assert.js.map",
+    "dist/matchers.js",
+    "dist/matchers.d.ts",
+    "dist/matchers.d.ts.map",
+    "dist/matchers.js.map",
+    "vitest.d.ts",
     "LICENSE",
     "README.md",
     "CHANGELOG.md"
   ],
   "scripts": {
     "build": "tsc",
+    "dev": "tsc --watch",
+    "docs": "typedoc",
     "test": "jest",
     "test:watch": "jest --watch",
     "test:coverage": "jest --coverage",
+    "benchmark": "npx tsx src/__tests__/benchmarks.ts 2>/dev/null",
     "lint": "eslint src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\"",
     "format:check": "prettier --check \"src/**/*.ts\"",
     "audit": "npm audit",
     "audit:fix": "npm audit fix",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "npm run build && npm run docs",
     "release:patch": "npm version patch && npm run build",
     "release:minor": "npm version minor && npm run build",
     "release:major": "npm version major && npm run build",
     "release:prerelease": "npm version prerelease && npm run build",
     "release:commit": "git add package.json CHANGELOG.md && git commit -m \"chore: release $(node -p \"require('./package.json').version\")\"",
-    "prepare": "husky"
+    "prepare": "husky || true"
+  },
+  "bin": {
+    "mcp-tester": "dist/cli/index.js"
   },
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-tester",
+    "mcp-client",
     "testing",
+    "test",
     "jest",
-    "ci-cd"
+    "vitest",
+    "assert",
+    "matchers",
+    "ci-cd",
+    "cli",
+    "typescript",
+    "esm"
   ],
   "author": "Slobodan Ivkovic",
   "license": "MIT",
@@ -53,9 +78,11 @@
   },
   "homepage": "https://github.com/islobodan/mcp-tester#readme",
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0"
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^14.0.3"
   },
   "devDependencies": {
+    "@modelcontextprotocol/server-everything": "^2026.1.26",
     "@types/jest": "^29.5.0",
     "@types/node": "^20.0.0",
     "@typescript-eslint/eslint-plugin": "^8.58.0",
@@ -66,6 +93,8 @@
     "lint-staged": "^16.4.0",
     "prettier": "^3.8.1",
     "ts-jest": "^29.4.9",
+    "typedoc": "^0.28.19",
+    "typedoc-plugin-markdown": "^4.11.0",
     "typescript": "^5.3.0"
   },
   "engines": {

package/vitest.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Vitest type declarations for MCP Tester custom matchers.
+ *
+ * Add this file to your tsconfig.json includes or reference it
+ * in your Vitest setup file to get type-safe matcher autocompletion.
+ *
+ * Usage (in vitest.d.ts or your setup file):
+ *   /// <reference types="@slbdn/mcp-tester/vitest" />
+ *
+ * Or add to tsconfig.json:
+ *   "include": ["node_modules/@slbdn/mcp-tester/vitest.d.ts"]
+ *
+ * Then in your Vitest setup:
+ *   import { setupVitestMatchers } from '@slbdn/mcp-tester';
+ *   beforeAll(() => setupVitestMatchers());
+ */
+
+import 'vitest';
+
+declare module 'vitest' {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  interface Matchers<R = void, T = unknown> {
+    // Collection matchers
+    toHaveTool(toolName: string): R;
+    toHaveResource(uri: string): R;
+    toHavePrompt(promptName: string): R;
+    toHaveToolWithSchema(toolName: string): R;
+    toHaveToolCount(count: number): R;
+    toHaveResourceCount(count: number): R;
+    toHavePromptCount(count: number): R;
+    toHaveResourceByName(name: string): R;
+    toHavePromptWithArgs(promptName: string): R;
+
+    // Tool result matchers
+    toReturnText(expected?: string): R;
+    toReturnTextContaining(substring: string): R;
+    toReturnError(): R;
+    toReturnOk(): R;
+    toReturnJson(expected: unknown): R;
+    toReturnContentCount(count: number): R;
+    toReturnImage(): R;
+
+    // Resource result matchers
+    toReturnResourceText(expected?: string): R;
+    toReturnResourceTextContaining(substring: string): R;
+
+    // Prompt result matchers
+    toReturnPromptTextContaining(substring: string): R;
+    toReturnPromptMessageCount(count: number): R;
+  }
+}