@mcpspec/core 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MCPSpec Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/http-XUWKDMSR.js

@@ -0,0 +1,9 @@
+// src/client/transports/http.ts
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+function createStreamableHTTPTransport(url) {
+  return new StreamableHTTPClientTransport(new URL(url));
+}
+export {
+  StreamableHTTPClientTransport,
+  createStreamableHTTPTransport
+};

package/dist/index.d.ts

@@ -0,0 +1,526 @@
+import * as _mcpspec_shared from '@mcpspec/shared';
+import { ErrorTemplate, ManagedProcess, ProcessConfig, ServerConfig, ConnectionConfig, ConnectionState, TestResult, TestRunResult, CollectionDefinition, RateLimitConfig, TestDefinition, SecurityScanMode, SeverityLevel, SecurityScanConfig, SecurityFinding, SecurityScanResult, ProfileEntry, BenchmarkStats, BenchmarkResult, BenchmarkConfig, WaterfallEntry, MCPScore } from '@mcpspec/shared';
+import { Transport, TransportSendOptions } from '@modelcontextprotocol/sdk/shared/transport.js';
+import { JSONRPCMessage, MessageExtraInfo } from '@modelcontextprotocol/sdk/types.js';
+
+type ErrorCode = 'CONNECTION_TIMEOUT' | 'CONNECTION_REFUSED' | 'CONNECTION_LOST' | 'PROCESS_SPAWN_FAILED' | 'PROCESS_CRASHED' | 'PROCESS_TIMEOUT' | 'TOOL_NOT_FOUND' | 'TOOL_CALL_FAILED' | 'INVALID_RESPONSE' | 'SCHEMA_VALIDATION_FAILED' | 'ASSERTION_FAILED' | 'COLLECTION_PARSE_ERROR' | 'COLLECTION_VALIDATION_ERROR' | 'YAML_PARSE_ERROR' | 'YAML_TOO_LARGE' | 'YAML_TOO_DEEP' | 'TIMEOUT' | 'RATE_LIMITED' | 'CONFIG_ERROR' | 'SECURITY_SCAN_ERROR' | 'NOT_IMPLEMENTED' | 'UNKNOWN_ERROR';
+declare const ERROR_CODE_MAP: Record<ErrorCode, number>;
+
+declare class MCPSpecError extends Error {
+    readonly code: ErrorCode;
+    readonly exitCode: number;
+    readonly context: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, context?: Record<string, unknown>);
+}
+declare class NotImplementedError extends MCPSpecError {
+    constructor(feature: string);
+}
+
+declare const ERROR_TEMPLATES: Record<string, ErrorTemplate>;
+
+interface FormattedError {
+    title: string;
+    description: string;
+    suggestions: string[];
+    docs?: string;
+    code: string;
+    exitCode: number;
+}
+declare function formatError(error: unknown): FormattedError;
+
+declare const YAML_LIMITS: {
+    maxFileSize: number;
+    maxNestingDepth: number;
+    maxTests: number;
+};
+declare function loadYamlSafely(content: string): unknown;
+
+declare class SecretMasker {
+    private secrets;
+    private static readonly REDACTED;
+    private static readonly SECRET_PATTERNS;
+    private static readonly MIN_SECRET_LENGTH;
+    register(secret: string): void;
+    registerFromEnv(env: Record<string, string>): void;
+    mask(text: string): string;
+    clear(): void;
+    get size(): number;
+}
+
+declare function resolveVariables(template: string, variables: Record<string, unknown>): string;
+
+/**
+ * Simple JSONPath implementation supporting basic dot notation.
+ * Supports: $.foo.bar, $.foo[0], $.foo[0].bar
+ */
+declare function queryJsonPath(data: unknown, path: string): unknown;
+
+interface PlatformInfo {
+    os: NodeJS.Platform;
+    arch: string;
+    release: string;
+    nodeVersion: string;
+    isWindows: boolean;
+    isMacOS: boolean;
+    isLinux: boolean;
+    tmpDir: string;
+    homeDir: string;
+    dataDir: string;
+}
+declare function getPlatformInfo(): PlatformInfo;
+
+declare class ProcessRegistry {
+    private processes;
+    register(process: ManagedProcess): void;
+    unregister(id: string): void;
+    get(id: string): ManagedProcess | undefined;
+    getAll(): ManagedProcess[];
+    has(id: string): boolean;
+    get size(): number;
+    clear(): void;
+}
+
+declare class ProcessManagerImpl {
+    private registry;
+    private readonly defaultGracePeriod;
+    constructor(registry?: ProcessRegistry);
+    spawn(config: ProcessConfig): Promise<ManagedProcess>;
+    shutdown(processId: string, gracePeriodMs?: number): Promise<void>;
+    shutdownAll(): Promise<void>;
+    isAlive(processId: string): boolean;
+    getRegistry(): ProcessRegistry;
+}
+
+declare function registerCleanupHandlers(manager: ProcessManagerImpl): void;
+
+interface ToolInfo {
+    name: string;
+    description?: string;
+    inputSchema?: Record<string, unknown>;
+}
+interface ResourceInfo {
+    uri: string;
+    name?: string;
+    description?: string;
+    mimeType?: string;
+}
+interface ToolCallResult {
+    content: unknown[];
+    isError?: boolean;
+}
+interface MCPClientInterface {
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    listTools(): Promise<ToolInfo[]>;
+    listResources(): Promise<ResourceInfo[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
+    readResource(uri: string): Promise<{
+        contents: unknown[];
+    }>;
+    getServerInfo(): {
+        name?: string;
+        version?: string;
+    } | undefined;
+}
+
+type OnProtocolMessage = (direction: 'outgoing' | 'incoming', message: Record<string, unknown>) => void;
+/**
+ * Wraps an SDK Transport to intercept and log all JSON-RPC messages.
+ */
+declare class LoggingTransport implements Transport {
+    private inner;
+    private callback;
+    constructor(inner: Transport, callback: OnProtocolMessage);
+    start(): Promise<void>;
+    send(message: JSONRPCMessage, options?: TransportSendOptions): Promise<void>;
+    close(): Promise<void>;
+    get onclose(): (() => void) | undefined;
+    set onclose(handler: (() => void) | undefined);
+    get onerror(): ((error: Error) => void) | undefined;
+    set onerror(handler: ((error: Error) => void) | undefined);
+    get onmessage(): (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) | undefined;
+    set onmessage(handler: (<T extends JSONRPCMessage>(message: T, extra?: MessageExtraInfo) => void) | undefined);
+    get sessionId(): string | undefined;
+    set sessionId(value: string | undefined);
+    get setProtocolVersion(): ((version: string) => void) | undefined;
+    set setProtocolVersion(handler: ((version: string) => void) | undefined);
+}
+
+interface MCPClientOptions {
+    serverConfig: ServerConfig | string;
+    processManager?: ProcessManagerImpl;
+    onProtocolMessage?: OnProtocolMessage;
+}
+declare class MCPClient implements MCPClientInterface {
+    private client;
+    private transport;
+    private connectionManager;
+    readonly processManager: ProcessManagerImpl;
+    private serverConfig;
+    private serverInfo;
+    private onProtocolMessage?;
+    constructor(options: MCPClientOptions);
+    private normalizeConfig;
+    connect(): Promise<void>;
+    private reconnect;
+    private createTransport;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    listTools(): Promise<ToolInfo[]>;
+    listResources(): Promise<ResourceInfo[]>;
+    callTool(name: string, args: Record<string, unknown>): Promise<ToolCallResult>;
+    readResource(uri: string): Promise<{
+        contents: unknown[];
+    }>;
+    getServerInfo(): {
+        name?: string;
+        version?: string;
+    } | undefined;
+    getConnectionState(): _mcpspec_shared.ConnectionState;
+    private ensureConnected;
+}
+
+declare class ConnectionManager {
+    private state;
+    private reconnectAttempts;
+    private config;
+    private listeners;
+    constructor(config?: Partial<ConnectionConfig>);
+    getState(): ConnectionState;
+    canTransition(to: ConnectionState): boolean;
+    transition(to: ConnectionState): void;
+    onTransition(listener: (from: ConnectionState, to: ConnectionState) => void): () => void;
+    shouldReconnect(): boolean;
+    getReconnectDelay(): number;
+    resetReconnectAttempts(): void;
+    getConfig(): ConnectionConfig;
+}
+
+interface TestRunnerOptions {
+    environment?: string;
+    reporter?: TestRunReporter;
+    parallelism?: number;
+    tags?: string[];
+    rateLimitConfig?: Partial<RateLimitConfig>;
+}
+interface TestRunReporter {
+    onRunStart(collectionName: string, testCount: number): void;
+    onTestStart(testName: string): void;
+    onTestComplete(result: TestResult): void;
+    onRunComplete(result: TestRunResult): void;
+    setSecretMasker?(masker: SecretMasker): void;
+}
+declare class TestRunner {
+    private processManager;
+    constructor();
+    run(collection: CollectionDefinition, options?: TestRunnerOptions): Promise<TestRunResult>;
+    private resolveServerConfig;
+    private computeSummary;
+    cleanup(): Promise<void>;
+}
+
+declare class RateLimiter {
+    private limiter;
+    private config;
+    constructor(config?: Partial<RateLimitConfig>);
+    schedule<T>(fn: () => Promise<T>): Promise<T>;
+    getConfig(): RateLimitConfig;
+    stop(): Promise<void>;
+}
+
+declare class TestExecutor {
+    private variables;
+    private rateLimiter;
+    constructor(initialVariables?: Record<string, unknown>, rateLimiter?: RateLimiter);
+    execute(test: TestDefinition, client: MCPClientInterface): Promise<TestResult>;
+    private executeWithTimeout;
+    private executeInternal;
+    private buildResponse;
+    private runAssertion;
+    private runSimpleExpectation;
+    getVariables(): Record<string, unknown>;
+}
+
+interface SchedulerOptions {
+    parallelism: number;
+    tags?: string[];
+    reporter?: TestRunReporter;
+    rateLimiter?: RateLimiter;
+    initialVariables?: Record<string, unknown>;
+}
+declare class TestScheduler {
+    schedule(tests: TestDefinition[], client: MCPClientInterface, options: SchedulerOptions): Promise<TestResult[]>;
+}
+
+declare class ConsoleReporter implements TestRunReporter {
+    private ci;
+    constructor(options?: {
+        ci?: boolean;
+    });
+    onRunStart(collectionName: string, testCount: number): void;
+    onTestStart(_testName: string): void;
+    onTestComplete(result: TestResult): void;
+    onRunComplete(result: TestRunResult): void;
+    private getIcon;
+}
+
+declare class JsonReporter implements TestRunReporter {
+    private readonly outputPath?;
+    private output;
+    constructor(outputPath?: string | undefined);
+    onRunStart(_collectionName: string, _testCount: number): void;
+    onTestStart(_testName: string): void;
+    onTestComplete(_result: TestResult): void;
+    onRunComplete(result: TestRunResult): void;
+    getOutput(): string | undefined;
+}
+
+declare class JunitReporter implements TestRunReporter {
+    private readonly outputPath?;
+    private output;
+    private secretMasker;
+    constructor(outputPath?: string | undefined);
+    setSecretMasker(masker: SecretMasker): void;
+    onRunStart(_collectionName: string, _testCount: number): void;
+    onTestStart(_testName: string): void;
+    onTestComplete(_result: TestResult): void;
+    onRunComplete(result: TestRunResult): void;
+    getOutput(): string | undefined;
+    private mask;
+}
+
+declare class HtmlReporter implements TestRunReporter {
+    private readonly outputPath?;
+    private output;
+    private secretMasker;
+    constructor(outputPath?: string | undefined);
+    setSecretMasker(masker: SecretMasker): void;
+    onRunStart(_collectionName: string, _testCount: number): void;
+    onTestStart(_testName: string): void;
+    onTestComplete(_result: TestResult): void;
+    onRunComplete(result: TestRunResult): void;
+    getOutput(): string | undefined;
+    private mask;
+}
+
+declare class TapReporter implements TestRunReporter {
+    private testIndex;
+    private secretMasker;
+    setSecretMasker(masker: SecretMasker): void;
+    onRunStart(_collectionName: string, testCount: number): void;
+    onTestStart(_testName: string): void;
+    onTestComplete(result: TestResult): void;
+    onRunComplete(_result: TestRunResult): void;
+    private mask;
+}
+
+declare class BaselineStore {
+    private basePath;
+    constructor(basePath?: string);
+    save(name: string, result: TestRunResult): string;
+    load(name: string): TestRunResult | null;
+    list(): string[];
+    private getFilePath;
+    private ensureDir;
+}
+
+interface TestDiff {
+    testName: string;
+    type: 'regression' | 'fix' | 'new' | 'removed' | 'unchanged';
+    before?: TestResult;
+    after?: TestResult;
+}
+interface RunDiff {
+    baselineName: string;
+    currentRunId: string;
+    regressions: TestDiff[];
+    fixes: TestDiff[];
+    newTests: TestDiff[];
+    removedTests: TestDiff[];
+    unchanged: TestDiff[];
+    summary: {
+        totalBefore: number;
+        totalAfter: number;
+        regressions: number;
+        fixes: number;
+        newTests: number;
+        removedTests: number;
+    };
+}
+declare class ResultDiffer {
+    diff(baseline: TestRunResult, current: TestRunResult, baselineName?: string): RunDiff;
+}
+
+declare class ScanConfig {
+    readonly mode: SecurityScanMode;
+    readonly rules: string[];
+    readonly severityThreshold: SeverityLevel;
+    readonly acknowledgeRisk: boolean;
+    readonly timeout: number;
+    readonly maxProbesPerTool: number;
+    constructor(config?: Partial<SecurityScanConfig>);
+    requiresConfirmation(): boolean;
+    meetsThreshold(severity: SeverityLevel): boolean;
+    private getRulesForMode;
+}
+
+interface SecurityRule {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+}
+
+interface ScanProgress {
+    onRuleStart?: (ruleId: string, ruleName: string) => void;
+    onRuleComplete?: (ruleId: string, findingCount: number) => void;
+    onFinding?: (finding: SecurityFinding) => void;
+}
+declare class SecurityScanner {
+    private readonly rules;
+    constructor();
+    registerRule(rule: SecurityRule): void;
+    scan(client: MCPClientInterface, config: ScanConfig, progress?: ScanProgress): Promise<SecurityScanResult>;
+    private buildSummary;
+    private registerBuiltinRules;
+}
+
+declare class PathTraversalRule implements SecurityRule {
+    readonly id = "path-traversal";
+    readonly name = "Path Traversal";
+    readonly description = "Tests for directory traversal vulnerabilities in path-based parameters";
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+    private findPathParams;
+}
+
+declare class InputValidationRule implements SecurityRule {
+    readonly id = "input-validation";
+    readonly name = "Input Validation";
+    readonly description = "Tests for missing or inadequate input validation";
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+    private getRequiredFields;
+    private getProperties;
+}
+
+declare class ResourceExhaustionRule implements SecurityRule {
+    readonly id = "resource-exhaustion";
+    readonly name = "Resource Exhaustion";
+    readonly description = "Tests for resource exhaustion vulnerabilities (DoS potential)";
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+    private getStringParams;
+    private createDeepObject;
+}
+
+declare class AuthBypassRule implements SecurityRule {
+    readonly id = "auth-bypass";
+    readonly name = "Auth Bypass";
+    readonly description = "Tests for unrestricted access to administrative or privileged tools";
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+    private getRequiredFields;
+}
+
+declare class InjectionRule implements SecurityRule {
+    readonly id = "injection";
+    readonly name = "Injection";
+    readonly description = "Tests for SQL injection, command injection, and template injection vulnerabilities";
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+    private getStringParams;
+}
+
+declare class InformationDisclosureRule implements SecurityRule {
+    readonly id = "information-disclosure";
+    readonly name = "Information Disclosure";
+    readonly description = "Tests for unintended information disclosure in error messages and responses";
+    scan(client: MCPClientInterface, tools: ToolInfo[], config: ScanConfig): Promise<SecurityFinding[]>;
+    private getFirstParam;
+}
+
+interface PayloadSet {
+    category: string;
+    label: string;
+    value: unknown;
+    description: string;
+}
+declare function getSafePayloads(): PayloadSet[];
+
+interface PlatformPayload {
+    category: string;
+    label: string;
+    value: string;
+    description: string;
+    minMode: SecurityScanMode;
+    platforms: NodeJS.Platform[];
+}
+declare function getPlatformPayloads(): PlatformPayload[];
+declare function getPayloadsForMode(mode: SecurityScanMode): PlatformPayload[];
+
+declare function computeStats(sortedDurations: number[]): BenchmarkStats;
+declare class Profiler {
+    private entries;
+    profileCall(client: MCPClientInterface, toolName: string, args: Record<string, unknown>): Promise<ProfileEntry>;
+    getEntries(): ProfileEntry[];
+    getStats(toolName?: string): BenchmarkStats;
+    clear(): void;
+}
+
+interface BenchmarkProgress {
+    onWarmupStart?: (iterations: number) => void;
+    onIterationComplete?: (iteration: number, total: number, durationMs: number) => void;
+    onComplete?: (result: BenchmarkResult) => void;
+}
+declare class BenchmarkRunner {
+    run(client: MCPClientInterface, toolName: string, args: Record<string, unknown>, config?: Partial<BenchmarkConfig>, progress?: BenchmarkProgress): Promise<BenchmarkResult>;
+    private runSingleIteration;
+}
+
+declare class WaterfallGenerator {
+    generate(entries: ProfileEntry[]): WaterfallEntry[];
+    toAscii(entries: WaterfallEntry[], width?: number): string;
+}
+
+interface ServerDocData {
+    serverName: string;
+    serverVersion?: string;
+    tools: ToolInfo[];
+    resources: ResourceInfo[];
+    generatedAt: Date;
+}
+declare class MarkdownGenerator {
+    generate(data: ServerDocData): string;
+}
+
+interface DocGeneratorOptions {
+    format: 'markdown' | 'html';
+    outputDir?: string;
+}
+declare class DocGenerator {
+    introspect(client: MCPClientInterface): Promise<ServerDocData>;
+    generate(client: MCPClientInterface, options: DocGeneratorOptions): Promise<string>;
+}
+
+declare class HtmlDocGenerator {
+    private template;
+    constructor();
+    generate(data: ServerDocData): string;
+}
+
+interface ScoreProgress {
+    onCategoryStart?: (category: string) => void;
+    onCategoryComplete?: (category: string, score: number) => void;
+}
+declare class MCPScoreCalculator {
+    calculate(client: MCPClientInterface, progress?: ScoreProgress): Promise<MCPScore>;
+    private scoreDocumentation;
+    private scoreSchemaQuality;
+    private scoreErrorHandling;
+    private scorePerformance;
+    private scoreSecurity;
+}
+
+declare class BadgeGenerator {
+    generate(score: MCPScore): string;
+    getColor(score: number): string;
+}
+
+export { AuthBypassRule, BadgeGenerator, BaselineStore, type BenchmarkProgress, BenchmarkRunner, ConnectionManager, ConsoleReporter, DocGenerator, type DocGeneratorOptions, ERROR_CODE_MAP, ERROR_TEMPLATES, type ErrorCode, HtmlDocGenerator, HtmlReporter, InformationDisclosureRule, InjectionRule, InputValidationRule, JsonReporter, JunitReporter, LoggingTransport, MCPClient, type MCPClientInterface, MCPScoreCalculator, MCPSpecError, MarkdownGenerator, NotImplementedError, type OnProtocolMessage, PathTraversalRule, type PayloadSet, type PlatformPayload, ProcessManagerImpl, ProcessRegistry, Profiler, RateLimiter, ResourceExhaustionRule, ResultDiffer, type RunDiff, ScanConfig, type ScanProgress, type ScoreProgress, SecretMasker, type SecurityRule, SecurityScanner, type ServerDocData, TapReporter, type TestDiff, TestExecutor, type TestRunReporter, TestRunner, TestScheduler, WaterfallGenerator, YAML_LIMITS, computeStats, formatError, getPayloadsForMode, getPlatformInfo, getPlatformPayloads, getSafePayloads, loadYamlSafely, queryJsonPath, registerCleanupHandlers, resolveVariables };