@bryan-thompson/inspector-assessment-client 1.12.0 → 1.13.0

package/lib/lib/policyMapping.js

@@ -0,0 +1,442 @@
+/**
+ * Policy Compliance Mapping Types
+ *
+ * Maps MCP Inspector assessment results to Anthropic's official Software Directory Policy
+ * requirements (30 total). Based on:
+ * - https://support.anthropic.com/en/articles/11697096-anthropic-mcp-directory-policy
+ * - https://support.claude.com/en/articles/12922490-remote-mcp-server-submission-guide
+ *
+ * @module policyMapping
+ */
+// ============================================================================
+// Anthropic Policy Requirements (30 Total)
+// ============================================================================
+/**
+ * Complete list of Anthropic's Software Directory Policy requirements.
+ *
+ * Organized by category:
+ * - Safety & Security: 6 requirements (SAFETY-1 to SAFETY-6)
+ * - Compatibility: 6 requirements (COMPAT-1 to COMPAT-6)
+ * - Functionality: 7 requirements (FUNC-1 to FUNC-7)
+ * - Developer Requirements: 8 requirements (DEV-1 to DEV-8)
+ * - Unsupported Use Cases: 3 requirements (UNSUPP-1 to UNSUPP-3)
+ */
+export const ANTHROPIC_POLICY_REQUIREMENTS = [
+    // ============================================================================
+    // SAFETY & SECURITY (6 requirements)
+    // ============================================================================
+    {
+        id: "SAFETY-1",
+        name: "AUP Compliance",
+        description: "MCP servers must not facilitate violation of Anthropic's Acceptable Use Policy (AUP). This includes all 14 prohibited categories (A-N).",
+        category: "safety_security",
+        severity: "CRITICAL",
+        moduleSource: ["aupCompliance"],
+        automatable: true,
+        policyReference: "Safety & Security Requirements",
+    },
+    {
+        id: "SAFETY-2",
+        name: "Universal Usage Standards",
+        description: "Servers must meet core safety requirements and universal usage standards as defined by Anthropic.",
+        category: "safety_security",
+        severity: "CRITICAL",
+        moduleSource: ["aupCompliance", "security"],
+        automatable: true,
+    },
+    {
+        id: "SAFETY-3",
+        name: "High-Risk Domain Compliance",
+        description: "Servers operating in high-risk domains (medical, legal, financial) must implement appropriate safeguards and disclaimers.",
+        category: "safety_security",
+        severity: "HIGH",
+        moduleSource: ["aupCompliance"],
+        automatable: false,
+    },
+    {
+        id: "SAFETY-4",
+        name: "OAuth 2.0 Security",
+        description: "Remote servers using authentication must implement OAuth 2.0 with PKCE and RFC 8707 resource indicators.",
+        category: "safety_security",
+        severity: "HIGH",
+        moduleSource: ["mcpSpecCompliance"],
+        automatable: false,
+    },
+    {
+        id: "SAFETY-5",
+        name: "No External Behavior Injection",
+        description: "Servers must not dynamically pull instructions from external sources that could modify Claude's behavior.",
+        category: "safety_security",
+        severity: "CRITICAL",
+        moduleSource: ["security"],
+        automatable: true,
+    },
+    {
+        id: "SAFETY-6",
+        name: "No Server Interference",
+        description: "Servers must not interfere with other MCP servers or the host system.",
+        category: "safety_security",
+        severity: "HIGH",
+        moduleSource: ["security"],
+        automatable: true,
+    },
+    // ============================================================================
+    // COMPATIBILITY (6 requirements)
+    // ============================================================================
+    {
+        id: "COMPAT-1",
+        name: "Streamable HTTP Transport",
+        description: "Remote servers must support Streamable HTTP transport for Claude web and mobile clients.",
+        category: "compatibility",
+        severity: "HIGH",
+        moduleSource: ["mcpSpecCompliance"],
+        automatable: false,
+    },
+    {
+        id: "COMPAT-2",
+        name: "SSE Deprecation Warning",
+        description: "Server-Sent Events (SSE) transport is deprecated. Servers should migrate to Streamable HTTP.",
+        category: "compatibility",
+        severity: "MEDIUM",
+        moduleSource: ["mcpSpecCompliance"],
+        automatable: true,
+    },
+    {
+        id: "COMPAT-3",
+        name: "Current Dependencies",
+        description: "Servers must use reasonably current package versions without known critical vulnerabilities.",
+        category: "compatibility",
+        severity: "MEDIUM",
+        moduleSource: ["prohibitedLibraries"],
+        automatable: true,
+    },
+    {
+        id: "COMPAT-4",
+        name: "Token Efficiency",
+        description: "Servers should use tokens frugally, with usage commensurate with the task complexity.",
+        category: "compatibility",
+        severity: "MEDIUM",
+        moduleSource: ["functionality"],
+        automatable: false,
+    },
+    {
+        id: "COMPAT-5",
+        name: "Response Size Limit",
+        description: "Tool responses should not exceed 25,000 tokens per response.",
+        category: "compatibility",
+        severity: "MEDIUM",
+        moduleSource: ["functionality"],
+        automatable: true,
+    },
+    {
+        id: "COMPAT-6",
+        name: "Cross-Platform Portability",
+        description: "Local servers must work across platforms without hardcoded paths or platform-specific assumptions.",
+        category: "compatibility",
+        severity: "MEDIUM",
+        moduleSource: ["portability"],
+        automatable: true,
+    },
+    // ============================================================================
+    // FUNCTIONALITY (7 requirements)
+    // ============================================================================
+    {
+        id: "FUNC-1",
+        name: "Reliable Performance",
+        description: "Servers must provide fast, reliable response times appropriate for the operation.",
+        category: "functionality",
+        severity: "HIGH",
+        moduleSource: ["functionality"],
+        automatable: true,
+    },
+    {
+        id: "FUNC-2",
+        name: "High Availability",
+        description: "Remote servers must maintain consistent uptime and availability.",
+        category: "functionality",
+        severity: "HIGH",
+        moduleSource: ["functionality"],
+        automatable: false,
+    },
+    {
+        id: "FUNC-3",
+        name: "Graceful Error Handling",
+        description: "Servers must provide helpful error feedback following MCP protocol. No generic 'unknown error' messages.",
+        category: "functionality",
+        severity: "HIGH",
+        moduleSource: ["errorHandling"],
+        automatable: true,
+    },
+    {
+        id: "FUNC-4",
+        name: "Tool Description Accuracy",
+        description: "Tool descriptions must accurately reflect actual functionality. No misleading or exaggerated claims.",
+        category: "functionality",
+        severity: "HIGH",
+        moduleSource: ["functionality", "documentation"],
+        automatable: false,
+    },
+    {
+        id: "FUNC-5",
+        name: "Tool Annotations Required",
+        description: "All tools must include readOnlyHint and destructiveHint annotations per MCP specification.",
+        category: "functionality",
+        severity: "HIGH",
+        moduleSource: ["toolAnnotations"],
+        automatable: true,
+        policyReference: "Policy #17",
+    },
+    {
+        id: "FUNC-6",
+        name: "No Unexpected Functionality",
+        description: "Servers must not include hidden functionality or fail to deliver promised features.",
+        category: "functionality",
+        severity: "HIGH",
+        moduleSource: ["functionality", "security"],
+        automatable: false,
+    },
+    {
+        id: "FUNC-7",
+        name: "Clear Tool Identity",
+        description: "Tools must have clear, non-conflicting descriptions that don't confuse with other servers.",
+        category: "functionality",
+        severity: "MEDIUM",
+        moduleSource: ["usability"],
+        automatable: true,
+    },
+    // ============================================================================
+    // DEVELOPER REQUIREMENTS (8 requirements)
+    // ============================================================================
+    {
+        id: "DEV-1",
+        name: "Privacy Policy",
+        description: "Developers must provide clear data handling documentation and privacy policy URLs.",
+        category: "developer_requirements",
+        severity: "HIGH",
+        moduleSource: ["manifestValidation", "documentation"],
+        automatable: true,
+    },
+    {
+        id: "DEV-2",
+        name: "Contact Information",
+        description: "Developers must provide verified support channels and contact information.",
+        category: "developer_requirements",
+        severity: "MEDIUM",
+        moduleSource: ["documentation"],
+        automatable: false,
+    },
+    {
+        id: "DEV-3",
+        name: "Documentation",
+        description: "Servers must include documentation explaining how the server works and troubleshooting guidance.",
+        category: "developer_requirements",
+        severity: "HIGH",
+        moduleSource: ["documentation"],
+        automatable: true,
+    },
+    {
+        id: "DEV-4",
+        name: "Testing Account",
+        description: "Developers must provide sample data or testing accounts for verification.",
+        category: "developer_requirements",
+        severity: "MEDIUM",
+        moduleSource: [],
+        automatable: false,
+    },
+    {
+        id: "DEV-5",
+        name: "Example Prompts",
+        description: "Servers must include at least 3 example prompts demonstrating core functionality.",
+        category: "developer_requirements",
+        severity: "HIGH",
+        moduleSource: ["documentation"],
+        automatable: true,
+        policyReference: "Policy #24",
+    },
+    {
+        id: "DEV-6",
+        name: "API Ownership",
+        description: "Developers must have control of or affiliation with connected API endpoints.",
+        category: "developer_requirements",
+        severity: "HIGH",
+        moduleSource: [],
+        automatable: false,
+    },
+    {
+        id: "DEV-7",
+        name: "Maintenance Commitment",
+        description: "Developers must commit to addressing issues in reasonable timeframes.",
+        category: "developer_requirements",
+        severity: "MEDIUM",
+        moduleSource: [],
+        automatable: false,
+    },
+    {
+        id: "DEV-8",
+        name: "Terms Agreement",
+        description: "Developers must accept MCP Directory Terms and Conditions.",
+        category: "developer_requirements",
+        severity: "CRITICAL",
+        moduleSource: [],
+        automatable: false,
+    },
+    // ============================================================================
+    // UNSUPPORTED USE CASES (3 requirements)
+    // ============================================================================
+    {
+        id: "UNSUPP-1",
+        name: "No Financial Transactions",
+        description: "Servers must not facilitate financial transactions, cryptocurrency, or money transfers.",
+        category: "unsupported_use_cases",
+        severity: "CRITICAL",
+        moduleSource: ["prohibitedLibraries", "aupCompliance"],
+        automatable: true,
+        policyReference: "Policy #28",
+    },
+    {
+        id: "UNSUPP-2",
+        name: "No Media Generation",
+        description: "Servers must not generate images, videos, or audio content.",
+        category: "unsupported_use_cases",
+        severity: "CRITICAL",
+        moduleSource: ["prohibitedLibraries", "aupCompliance"],
+        automatable: true,
+        policyReference: "Policy #29",
+    },
+    {
+        id: "UNSUPP-3",
+        name: "No Cross-Service Orchestration",
+        description: "Servers must not orchestrate actions across unrelated third-party services.",
+        category: "unsupported_use_cases",
+        severity: "HIGH",
+        moduleSource: ["aupCompliance"],
+        automatable: false,
+        policyReference: "Policy #30",
+    },
+];
+// ============================================================================
+// Helper Functions
+// ============================================================================
+/**
+ * Get all requirements for a specific category
+ */
+export function getRequirementsByCategory(category) {
+    return ANTHROPIC_POLICY_REQUIREMENTS.filter((r) => r.category === category);
+}
+/**
+ * Get a specific requirement by ID
+ */
+export function getRequirementById(id) {
+    return ANTHROPIC_POLICY_REQUIREMENTS.find((r) => r.id === id);
+}
+/**
+ * Get all requirements that a specific module provides evidence for
+ */
+export function getRequirementsForModule(moduleName) {
+    return ANTHROPIC_POLICY_REQUIREMENTS.filter((r) => r.moduleSource.includes(moduleName));
+}
+/**
+ * Get all critical requirements
+ */
+export function getCriticalRequirements() {
+    return ANTHROPIC_POLICY_REQUIREMENTS.filter((r) => r.severity === "CRITICAL");
+}
+/**
+ * Get all automatable requirements
+ */
+export function getAutomatableRequirements() {
+    return ANTHROPIC_POLICY_REQUIREMENTS.filter((r) => r.automatable);
+}
+/**
+ * Get human-readable category name
+ */
+export function getCategoryDisplayName(category) {
+    const names = {
+        safety_security: "Safety & Security",
+        compatibility: "Compatibility",
+        functionality: "Functionality",
+        developer_requirements: "Developer Requirements",
+        unsupported_use_cases: "Unsupported Use Cases",
+    };
+    return names[category];
+}
+/**
+ * Convert ComplianceStatus to AssessmentStatus
+ */
+export function complianceToAssessmentStatus(status) {
+    switch (status) {
+        case "PASS":
+            return "PASS";
+        case "FAIL":
+        case "FLAG":
+            return "FAIL";
+        case "REVIEW":
+        case "NOT_TESTED":
+        case "NOT_APPLICABLE":
+            return "NEED_MORE_INFO";
+    }
+}
+/**
+ * Calculate compliance score from results
+ */
+export function calculateComplianceScore(results) {
+    const applicableResults = results.filter((r) => r.status !== "NOT_APPLICABLE" && r.status !== "NOT_TESTED");
+    if (applicableResults.length === 0)
+        return 0;
+    const passed = applicableResults.filter((r) => r.status === "PASS").length;
+    return Math.round((passed / applicableResults.length) * 100);
+}
+/**
+ * Determine overall compliance status
+ */
+export function determineOverallStatus(results) {
+    // Check for any critical failures
+    const criticalFailures = results.filter((r) => r.requirement.severity === "CRITICAL" && r.status === "FAIL");
+    if (criticalFailures.length > 0) {
+        return "NON_COMPLIANT";
+    }
+    // Check for any failures
+    const failures = results.filter((r) => r.status === "FAIL");
+    if (failures.length > 0) {
+        return "NON_COMPLIANT";
+    }
+    // Check if any need review
+    const needsReview = results.filter((r) => r.status === "REVIEW" || r.status === "FLAG");
+    if (needsReview.length > 0) {
+        return "NEEDS_REVIEW";
+    }
+    return "COMPLIANT";
+}
+// ============================================================================
+// Module-to-Policy Mapping
+// ============================================================================
+/**
+ * Mapping of assessment modules to the policy requirements they satisfy.
+ * Used by PolicyComplianceGenerator to map results.
+ */
+export const MODULE_TO_POLICY_MAP = {
+    aupCompliance: [
+        "SAFETY-1",
+        "SAFETY-2",
+        "SAFETY-3",
+        "UNSUPP-1",
+        "UNSUPP-2",
+        "UNSUPP-3",
+    ],
+    security: ["SAFETY-2", "SAFETY-5", "SAFETY-6", "FUNC-6"],
+    functionality: ["COMPAT-4", "COMPAT-5", "FUNC-1", "FUNC-4", "FUNC-6"],
+    errorHandling: ["FUNC-3"],
+    usability: ["FUNC-7"],
+    documentation: ["DEV-1", "DEV-3", "DEV-5", "FUNC-4"],
+    mcpSpecCompliance: ["SAFETY-4", "COMPAT-1", "COMPAT-2"],
+    toolAnnotations: ["FUNC-5"],
+    prohibitedLibraries: ["COMPAT-3", "UNSUPP-1", "UNSUPP-2"],
+    manifestValidation: ["DEV-1"],
+    portability: ["COMPAT-6"],
+};
+/**
+ * Get which policy requirements are evaluated by a given module
+ */
+export function getPolicyRequirementsForModule(moduleName) {
+    return MODULE_TO_POLICY_MAP[moduleName] || [];
+}

package/lib/lib/reportFormatters/MarkdownReportFormatter.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Markdown Report Formatter
+ *
+ * Generates human-readable markdown reports from MCP assessment results.
+ * Designed for reviewers, auditors, and developers.
+ *
+ * @module MarkdownReportFormatter
+ */
+import type { MCPDirectoryAssessment } from "../assessmentTypes.js";
+import type { PolicyComplianceReport } from "../policyMapping.js";
+/**
+ * Options for markdown report generation
+ */
+export interface MarkdownReportOptions {
+    /** Include policy compliance section */
+    includePolicy?: boolean;
+    /** Policy compliance report (required if includePolicy is true) */
+    policyReport?: PolicyComplianceReport;
+    /** Include detailed module results */
+    includeDetails?: boolean;
+    /** Include recommendations */
+    includeRecommendations?: boolean;
+    /** Server name override */
+    serverName?: string;
+}
+/**
+ * Formats assessment results as Markdown
+ */
+export declare class MarkdownReportFormatter {
+    private options;
+    constructor(options?: MarkdownReportOptions);
+    /**
+     * Format assessment results as markdown
+     */
+    format(assessment: MCPDirectoryAssessment): string;
+    /**
+     * Format header section
+     */
+    private formatHeader;
+    /**
+     * Format executive summary
+     */
+    private formatExecutiveSummary;
+    /**
+     * Format module status table
+     */
+    private formatModuleStatusTable;
+    /**
+     * Format a single module row
+     */
+    private formatModuleRow;
+    /**
+     * Format key findings section
+     */
+    private formatKeyFindings;
+    /**
+     * Format policy compliance section
+     */
+    private formatPolicyCompliance;
+    /**
+     * Format recommendations section
+     */
+    private formatRecommendations;
+    /**
+     * Format detailed results section
+     */
+    private formatDetailedResults;
+    /**
+     * Format footer section
+     */
+    private formatFooter;
+    private getStatusEmoji;
+    private getComplianceStatusEmoji;
+    private complianceToAssessment;
+    private getFunctionalityFinding;
+    private getSecurityFinding;
+    private getErrorHandlingFinding;
+    private getDocumentationFinding;
+    private getUsabilityFinding;
+    private getMCPSpecFinding;
+    private getAUPFinding;
+    private getAnnotationFinding;
+    private getCriticalIssues;
+    private getWarnings;
+    private getPositiveFindings;
+}
+/**
+ * Create a markdown formatter with options
+ */
+export declare function createMarkdownFormatter(options?: MarkdownReportOptions): MarkdownReportFormatter;
+//# sourceMappingURL=MarkdownReportFormatter.d.ts.map

package/lib/lib/reportFormatters/MarkdownReportFormatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MarkdownReportFormatter.d.ts","sourceRoot":"","sources":["../../../src/lib/reportFormatters/MarkdownReportFormatter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,sBAAsB,EAEvB,MAAM,kBAAkB,CAAC;AAE1B;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,wCAAwC;IACxC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,mEAAmE;IACnE,YAAY,CAAC,EAAE,sBAAsB,CAAC;IACtC,sCAAsC;IACtC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,8BAA8B;IAC9B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,2BAA2B;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,qBAAa,uBAAuB;IAClC,OAAO,CAAC,OAAO,CAAwB;gBAE3B,OAAO,GAAE,qBAA0B;IAQ/C;;OAEG;IACH,MAAM,CAAC,UAAU,EAAE,sBAAsB,GAAG,MAAM;IAoClD;;OAEG;IACH,OAAO,CAAC,YAAY;IAYpB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IAkC9B;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAgF/B;;OAEG;IACH,OAAO,CAAC,eAAe;IAUvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAmCzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA2D9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAkD7B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAwE7B;;OAEG;IACH,OAAO,CAAC,YAAY;IAkBpB,OAAO,CAAC,cAAc;IAatB,OAAO,CAAC,wBAAwB;IAmBhC,OAAO,CAAC,sBAAsB;IAa9B,OAAO,CAAC,uBAAuB;IAS/B,OAAO,CAAC,kBAAkB;IAM1B,OAAO,CAAC,uBAAuB;IAO/B,OAAO,CAAC,uBAAuB;IAQ/B,OAAO,CAAC,mBAAmB;IAM3B,OAAO,CAAC,iBAAiB;IAMzB,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,oBAAoB;IAQ5B,OAAO,CAAC,iBAAiB;IA8BzB,OAAO,CAAC,WAAW;IA4BnB,OAAO,CAAC,mBAAmB;CAiC5B;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,CAAC,EAAE,qBAAqB,GAC9B,uBAAuB,CAEzB"}