@securityreviewai/security-review-mcp 0.2.9

package/README.md

@@ -0,0 +1,264 @@
+# Security Review MCP
+
+TypeScript MCP server for [SecurityReview.ai](https://securityreview.ai), published as an `npx`-runnable package.
+
+- Pure Node runtime (no Python bootstrap)
+- Stdio MCP server compatible with Cursor, Windsurf, Claude Desktop, ChatGPT MCP, and other MCP clients
+- 53 tools for project/document/review/workflow/integration operations
+- 8 built-in security-analysis prompts
+- 4 read-only MCP resources
+
+## Install / Run
+
+Run directly with `npx`:
+
+```bash
+npx -y security-review-mcp \
+  --api-url https://api.example.com \
+  --api-token YOUR_API_TOKEN
+```
+
+Or provide credentials via `.env` in your current working directory:
+
+```env
+SECURITY_REVIEW_API_URL=https://api.example.com
+SECURITY_REVIEW_API_TOKEN=YOUR_API_TOKEN
+```
+
+Then run:
+
+```bash
+npx -y security-review-mcp
+```
+
+## MCP Client Configuration
+
+### Cursor / Windsurf
+
+```json
+{
+  "mcpServers": {
+    "security-review-mcp": {
+      "command": "npx",
+      "args": ["-y", "security-review-mcp"],
+      "env": {
+        "SECURITY_REVIEW_API_URL": "https://api.example.com",
+        "SECURITY_REVIEW_API_TOKEN": "YOUR_API_TOKEN"
+      }
+    }
+  }
+}
+```
+
+### With Jira + Confluence Integration
+
+```json
+{
+  "mcpServers": {
+    "security-review-mcp": {
+      "command": "npx",
+      "args": ["-y", "security-review-mcp"],
+      "env": {
+        "SECURITY_REVIEW_API_URL": "https://api.example.com",
+        "SECURITY_REVIEW_API_TOKEN": "YOUR_API_TOKEN",
+        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
+        "JIRA_EMAIL": "you@company.com",
+        "JIRA_API_TOKEN": "YOUR_JIRA_TOKEN",
+        "CONFLUENCE_BASE_URL": "https://yourcompany.atlassian.net",
+        "CONFLUENCE_EMAIL": "you@company.com",
+        "CONFLUENCE_API_TOKEN": "YOUR_CONFLUENCE_TOKEN"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---:|---|
+| `SECURITY_REVIEW_API_URL` | Yes* | SecurityReview API base URL |
+| `SECURITY_REVIEW_API_TOKEN` | Yes* | SecurityReview API bearer token |
+| `SRAI_API_URL` | Yes* | Backward-compatible API URL alias |
+| `SRAI_API_TOKEN` | Yes* | Backward-compatible API token alias |
+| `JIRA_BASE_URL` | No | Jira base URL |
+| `JIRA_EMAIL` | No | Jira user email |
+| `JIRA_API_TOKEN` | No | Jira API token |
+| `CONFLUENCE_BASE_URL` | No | Confluence base URL |
+| `CONFLUENCE_EMAIL` | No | Confluence user email |
+| `CONFLUENCE_API_TOKEN` | No | Confluence API token |
+
+\* Either `SECURITY_REVIEW_*` or `SRAI_*` must be present.
+
+## CLI Options
+
+- `--api-url <url>`
+- `--api-token <token>`
+- `--env-file <path>`
+- `--jira-base-url <url>`
+- `--jira-email <email>`
+- `--jira-api-token <token>`
+- `--confluence-base-url <url>`
+- `--confluence-email <email>`
+- `--confluence-api-token <token>`
+- `--print-config`
+- `--help`
+
+Compatibility flags (no-op, retained for older configs):
+- `--python <path>`
+- `--force-install`
+
+## Tool Catalog (53)
+
+### Projects
+
+| Tool | Purpose |
+|---|---|
+| `list_projects` | List all projects |
+| `get_project` | Get project details by ID |
+| `create_project` | Create a new project |
+| `get_project_settings` | Get project settings/configuration |
+| `get_project_profile` | Get project profile hub summary |
+| `get_full_project_profile` | Get full project profile graph payload |
+| `get_project_profile_description` | Get project profile description |
+| `list_profile_technology_categories` | List technology categories in project profile |
+| `get_project_profile_technology_category` | Get one technology category by name |
+| `list_project_profile_architecture_notes` | List architecture notes in project profile |
+| `list_project_profile_user_groups` | List user groups in project profile |
+| `list_project_profile_language_stacks` | List language stacks in project profile |
+| `list_project_profile_security_controls` | List security controls in project profile |
+| `get_project_profile_security_control` | Get one security control by ID |
+| `list_profile_compliance_requirements` | List compliance requirements in project profile |
+| `get_profile_compliance_requirement` | Get one compliance requirement by ID |
+
+### Documents
+
+| Tool | Purpose |
+|---|---|
+| `list_documents` | List project documents |
+| `get_document` | Get document details by ID |
+| `get_document_evaluation` | Get processed document evaluation |
+| `upload_component_diagram` | Upload component diagram from local file path |
+| `upload_document` | Upload base64 file content |
+| `create_document_from_content` | Create/upload a text document from content |
+| `link_external_document` | Link Jira/Confluence/GitHub document references |
+
+### Reviews
+
+| Tool | Purpose |
+|---|---|
+| `find_project_by_name` | Fuzzy project lookup by name |
+| `list_reviews` | List reviews in a project |
+| `list_reviews_by_project_name` | Resolve project name then list reviews |
+| `get_review` | Get review details by ID |
+| `get_review_overview` | Build intent-focused review summary and artifacts |
+| `create_review` | Create a review with step config |
+| `get_review_resource_documents` | List available docs for review creation |
+| `get_review_resource_compliance` | List available compliance frameworks |
+
+### Workflow
+
+| Tool | Purpose |
+|---|---|
+| `list_ai_ide_workflows` | List AI IDE workflows in a project |
+| `get_ai_ide_workflow` | Get AI IDE workflow by ID |
+| `create_ai_ide_workflow` | Create AI IDE workflow for a project |
+| `create_ai_ide_event` | Create AI IDE event within a workflow |
+| `start_workflow` | Start review workflow |
+| `get_workflow_status` | Get workflow status |
+| `get_workflow_job_status` | Get status for a specific job |
+| `start_next_workflow_job` | Start next pending job |
+| `start_workflow_job` | Start specific job by ID |
+| `retry_workflow_job` | Retry a failed job |
+
+### Integrations
+
+| Tool | Purpose |
+|---|---|
+| `fetch_jira_issue` | Fetch Jira issue content |
+| `fetch_confluence_page` | Fetch Confluence page by ID or URL |
+| `search_confluence_pages` | Search Confluence via CQL |
+| `fetch_and_link_to_srai` | Link Jira/Confluence source to SRAI project |
+
+### Review Artifacts
+
+| Tool | Purpose |
+|---|---|
+| `get_security_objectives` | Fetch review security objectives |
+| `get_threat_scenarios` | Fetch threat scenarios |
+| `get_countermeasures` | Fetch countermeasures |
+| `get_components` | Fetch identified system components/entities |
+| `get_data_dictionaries` | Fetch data dictionaries |
+| `get_questions` | Fetch generated security questions |
+| `get_findings` | Fetch review findings |
+| `get_security_test_cases` | Fetch security test cases |
+
+## Prompt Catalog (8)
+
+| Prompt | Purpose |
+|---|---|
+| `full_security_analysis` | End-to-end structured security review |
+| `security_objectives_analysis` | Security objectives and requirement extraction |
+| `component_analysis` | Architecture/component extraction |
+| `data_dictionary_analysis` | Sensitive data and stepping stone identification |
+| `threat_analysis` | Threat generation with CVSS-oriented guidance |
+| `countermeasure_analysis` | Mitigation/control generation |
+| `code_security_review` | Security-focused code review guidance |
+| `document_generation` | Generate architecture/API/deployment documents from brief input |
+
+## Resource Catalog (4)
+
+| Resource URI | Description |
+|---|---|
+| `srai://projects` | List all projects |
+| `srai://projects/{project_id}/reviews` | List project reviews |
+| `srai://projects/{project_id}/reviews/{review_id}/summary` | Review summary |
+| `srai://projects/{project_id}/documents` | List project documents |
+
+## Typical Workflows
+
+### 1) Review Existing Project Artifacts
+
+1. `find_project_by_name`
+2. `list_reviews_by_project_name`
+3. `get_review_overview`
+4. `get_threat_scenarios` / `get_findings`
+
+### 2) Create a New Review from Documents
+
+1. `create_project`
+2. `upload_document` or `create_document_from_content`
+3. `create_review`
+4. `start_workflow`
+5. `get_workflow_status`
+
+### 3) Bring in Jira/Confluence Context
+
+1. `fetch_jira_issue` or `fetch_confluence_page`
+2. `link_external_document` or `fetch_and_link_to_srai`
+3. `create_review`
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|---|---|---|
+| `Missing API URL` | API URL not set | Set `SECURITY_REVIEW_API_URL` or `SRAI_API_URL` |
+| `Missing API token` | API token not set | Set `SECURITY_REVIEW_API_TOKEN` or `SRAI_API_TOKEN` |
+| Integration tool returns config error | Jira/Confluence env vars missing | Set required integration env vars |
+| `npx` install errors | Network/auth/cache issue | Retry with a valid npm auth/network setup; clear/fix npm cache if needed |
+
+## Development
+
+```bash
+npm install
+npm run build
+node dist/bin/security-review-mcp.js --help
+```
+
+## Runtime Requirements
+
+- Node.js `>=18`
+
+## License
+
+UNLICENSED

package/dist/api/client.js

@@ -0,0 +1,345 @@
+export const DEFAULT_TIMEOUT_MS = 60_000;
+export class SraiApiError extends Error {
+    statusCode;
+    detail;
+    url;
+    constructor(statusCode, detail, url = "") {
+        super(`SRAI API error ${statusCode} on ${url}: ${detail}`);
+        this.statusCode = statusCode;
+        this.detail = detail;
+        this.url = url;
+    }
+}
+export class SraiApiClient {
+    baseUrl;
+    apiToken;
+    timeoutMs;
+    constructor(baseUrl, apiToken, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        let configuredBaseUrl = (baseUrl || process.env.SRAI_API_URL || "").replace(/\/+$/u, "");
+        if (configuredBaseUrl.endsWith("/api")) {
+            configuredBaseUrl = configuredBaseUrl.slice(0, -4);
+        }
+        const configuredToken = apiToken || process.env.SRAI_API_TOKEN || "";
+        if (!configuredBaseUrl) {
+            throw new Error("SRAI_API_URL is not configured. Set the environment variable.");
+        }
+        if (!configuredToken) {
+            throw new Error("SRAI_API_TOKEN is not configured. Set the environment variable.");
+        }
+        this.baseUrl = configuredBaseUrl;
+        this.apiToken = configuredToken;
+        this.timeoutMs = timeoutMs;
+    }
+    headers(options = {}) {
+        const { includeJsonAccept = true, includeJsonContentType = false } = options;
+        return {
+            Authorization: `Bearer ${this.apiToken}`,
+            ...(includeJsonAccept ? { Accept: "application/json" } : {}),
+            ...(includeJsonContentType ? { "Content-Type": "application/json" } : {}),
+        };
+    }
+    buildUrl(pathname, params) {
+        const url = new URL(`${this.baseUrl}${pathname}`);
+        if (params) {
+            for (const [key, rawValue] of Object.entries(params)) {
+                if (rawValue === undefined) {
+                    continue;
+                }
+                url.searchParams.set(key, String(rawValue));
+            }
+        }
+        return url.toString();
+    }
+    async request(method, path, options = {}) {
+        const url = this.buildUrl(path, options.params);
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+        try {
+            const hasFormData = Boolean(options.formData);
+            const hasJsonBody = options.jsonBody !== undefined;
+            const requestInit = {
+                method,
+                headers: this.headers({
+                    includeJsonAccept: !hasFormData,
+                    includeJsonContentType: !hasFormData && hasJsonBody,
+                }),
+                redirect: "follow",
+                signal: controller.signal,
+            };
+            if (options.formData) {
+                requestInit.body = options.formData;
+            }
+            else if (options.jsonBody === undefined) {
+                requestInit.body = null;
+            }
+            else {
+                requestInit.body = toJsonRequestBody(options.jsonBody);
+            }
+            const response = await fetch(url, requestInit);
+            if (response.status >= 400) {
+                const detail = await parseErrorBody(response);
+                throw new SraiApiError(response.status, detail, url);
+            }
+            if (response.status === 204) {
+                return { status: "ok" };
+            }
+            const text = await response.text();
+            if (!text) {
+                return { status: "ok" };
+            }
+            const contentType = (response.headers.get("content-type") || "").toLowerCase();
+            if (!contentType.includes("application/json")) {
+                const preview = text.slice(0, 300);
+                throw new SraiApiError(response.status, `Expected JSON response from SRAI API but got non-JSON content. Content-Type='${contentType}'. Response starts with: ${preview}`, url);
+            }
+            try {
+                return JSON.parse(text);
+            }
+            catch (error) {
+                throw new SraiApiError(response.status, `Failed to parse JSON response: ${String(error)}`, url);
+            }
+        }
+        catch (error) {
+            if (error instanceof SraiApiError) {
+                throw error;
+            }
+            if (error instanceof Error && error.name === "AbortError") {
+                throw new SraiApiError(408, `Request timed out after ${this.timeoutMs}ms`, url);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    async listProjects() {
+        return this.request("GET", "/api/projects");
+    }
+    async getProject(projectId) {
+        return this.request("GET", `/api/projects/${projectId}`);
+    }
+    async createProject(name, description) {
+        return this.request("POST", "/api/projects", {
+            jsonBody: { name, description },
+        });
+    }
+    async getProjectSettings(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/settings`);
+    }
+    async getLatestProfileVersion(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile-versions/`);
+    }
+    async getProjectProfile(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile`);
+    }
+    async getFullProjectProfile(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/full`);
+    }
+    async getProjectProfileDescription(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/description`);
+    }
+    async listProjectProfileTechnologyCategories(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/technology-categories`);
+    }
+    async getProjectProfileTechnologyCategory(projectId, categoryName) {
+        return this.request("GET", `/api/projects/${projectId}/profile/technology-categories/${encodeURIComponent(categoryName)}`);
+    }
+    async listProjectProfileArchitectureNotes(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/architecture-notes`);
+    }
+    async listProjectProfileUserGroups(projectId, groupType) {
+        return this.request("GET", `/api/projects/${projectId}/profile/user-groups`, {
+            params: {
+                group_type: groupType,
+            },
+        });
+    }
+    async listProjectProfileLanguageStacks(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/language-stacks`);
+    }
+    async listProjectProfileSecurityControls(projectId, status) {
+        return this.request("GET", `/api/projects/${projectId}/profile/security-controls`, {
+            params: {
+                status,
+            },
+        });
+    }
+    async getProjectProfileSecurityControl(projectId, controlId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/security-controls/${controlId}`);
+    }
+    async listProjectProfileComplianceRequirements(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/compliance-requirements`);
+    }
+    async getProjectProfileComplianceRequirement(projectId, requirementId) {
+        return this.request("GET", `/api/projects/${projectId}/profile/compliance-requirements/${requirementId}`);
+    }
+    async listDocuments(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/documents`);
+    }
+    async getDocument(projectId, documentId) {
+        return this.request("GET", `/api/projects/${projectId}/documents/${documentId}`);
+    }
+    async getDocumentEvaluation(projectId, documentId) {
+        return this.request("GET", `/api/projects/${projectId}/documents/${documentId}/evaluation`);
+    }
+    async uploadDocument(projectId, name, description, documentType, fileContent, fileName) {
+        const form = new FormData();
+        form.set("name", name);
+        form.set("description", description);
+        form.set("document_type", documentType);
+        form.set("file", new Blob([toArrayBuffer(fileContent)], { type: "application/octet-stream" }), fileName);
+        return this.request("POST", `/api/projects/${projectId}/documents/upload`, {
+            formData: form,
+        });
+    }
+    async uploadComponentDiagram(projectId, name, description, fileContent, fileName, contentType = "application/octet-stream") {
+        const form = new FormData();
+        form.set("name", name);
+        form.set("description", description);
+        form.set("document_type", "Component Diagram");
+        form.set("file", new Blob([toArrayBuffer(fileContent)], { type: contentType }), fileName);
+        return this.request("POST", `/api/projects/${projectId}/documents/upload`, {
+            formData: form,
+        });
+    }
+    async linkDocument(projectId, payload) {
+        return this.request("POST", `/api/projects/${projectId}/documents/link`, {
+            jsonBody: payload,
+        });
+    }
+    async listReviews(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews`);
+    }
+    async getReview(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}`);
+    }
+    async createReview(projectId, reviewConfig) {
+        return this.request("POST", `/api/projects/${projectId}/reviews`, {
+            jsonBody: reviewConfig,
+        });
+    }
+    async getReviewResourceDocuments(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/resources/documents`);
+    }
+    async getReviewResourceComponentDiagrams(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/resources/component-diagrams`);
+    }
+    async getReviewResourceCompliance(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/resources/compliance`);
+    }
+    async startWorkflow(projectId, reviewId) {
+        return this.request("POST", `/api/projects/${projectId}/reviews/${reviewId}/workflow/start`);
+    }
+    async getWorkflowStatus(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/workflow`);
+    }
+    async getWorkflowJobStatus(projectId, reviewId, jobId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/workflow/status/${jobId}`);
+    }
+    async startWorkflowJob(projectId, reviewId, jobId) {
+        return this.request("POST", `/api/projects/${projectId}/reviews/${reviewId}/workflow/jobs/${jobId}/start`);
+    }
+    async retryWorkflowJob(projectId, reviewId, jobId) {
+        return this.request("POST", `/api/projects/${projectId}/reviews/${reviewId}/workflow/jobs/${jobId}/retry`);
+    }
+    async getNextWorkflowJob(projectId, reviewId) {
+        return this.request("POST", `/api/projects/${projectId}/reviews/${reviewId}/workflow/next`);
+    }
+    async createAiIdeWorkflow(projectId, name, description) {
+        return this.request("POST", `/api/projects/${projectId}/ai-ide/workflows`, {
+            jsonBody: {
+                name,
+                description,
+            },
+        });
+    }
+    async listAiIdeWorkflows(projectId, page = 1, pageSize = 10) {
+        return this.request("GET", `/api/projects/${projectId}/ai-ide/workflows`, {
+            params: {
+                page,
+                page_size: pageSize,
+            },
+        });
+    }
+    async getAiIdeWorkflow(projectId, workflowId) {
+        return this.request("GET", `/api/projects/${projectId}/ai-ide/workflows/${workflowId}`);
+    }
+    async createAiIdeEvent(projectId, workflowId, payload) {
+        return this.request("POST", `/api/projects/${projectId}/ai-ide/workflows/${workflowId}/events`, {
+            jsonBody: payload,
+        });
+    }
+    async getSecurityObjectives(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/security-objectives`);
+    }
+    async getThreatScenarios(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/threat-scenarios`);
+    }
+    async getDataDictionaries(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/data-dictionaries`);
+    }
+    async getCountermeasures(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/countermeasures`);
+    }
+    async getComponents(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/entity`);
+    }
+    async getQuestions(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/questions`);
+    }
+    async getFindings(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/findings`);
+    }
+    async getSecurityTestCases(projectId, reviewId) {
+        return this.request("GET", `/api/projects/${projectId}/reviews/${reviewId}/security-test-cases`);
+    }
+    async listJiraProjects(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/integrations/jira/projects`);
+    }
+    async listConfluenceSpaces(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/integrations/confluence/spaces`);
+    }
+    async listGithubRepos(projectId) {
+        return this.request("GET", `/api/projects/${projectId}/integrations/github/repos`);
+    }
+}
+async function parseErrorBody(response) {
+    const text = await response.text();
+    if (!text) {
+        return `HTTP ${response.status}`;
+    }
+    try {
+        return JSON.stringify(JSON.parse(text));
+    }
+    catch {
+        return text;
+    }
+}
+let singletonClient;
+export function getApiClient() {
+    if (!singletonClient) {
+        singletonClient = new SraiApiClient();
+    }
+    return singletonClient;
+}
+export function resetApiClientForTests() {
+    singletonClient = undefined;
+}
+function toArrayBuffer(content) {
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    return buffer.buffer.slice(buffer.byteOffset, buffer.byteOffset + buffer.byteLength);
+}
+function toJsonRequestBody(payload) {
+    // If a JSON object was accidentally pre-stringified upstream, forward it as-is
+    // to avoid double encoding (which turns objects into JSON strings).
+    if (typeof payload === "string") {
+        try {
+            JSON.parse(payload);
+            return payload;
+        }
+        catch {
+            return JSON.stringify(payload);
+        }
+    }
+    return JSON.stringify(payload);
+}