@convisoappsec/mcp 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Conviso
+
+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/README.md

@@ -0,0 +1,124 @@
+<img src="assets/conviso_banner.png" width="128">
+
+# Conviso MCP Server
+
+This repository contains both a Python and a Node.js MCP server. This `node/` folder is the Node.js bundle and is packaged into the `.mcpb` bundle for MCP clients that run Node runtimes.
+
+## 🛠 Available Tools (Capabilities)
+
+The server exposes the following tools to the LLM (see `node/manifest.json` for the authoritative definitions):
+
+| Category | Tool | Description |
+| --- | --- | --- |
+| **General** | `get_companies` | List companies and associated IDs. |
+| **General** | `get_company_info` | Plan details, integrations, and company branding info. |
+| **Vulnerabilities** | `get_issues` | List vulnerabilities by company or project. |
+| **Vulnerabilities** | `get_issue` | Technical details, including **code snippets** and raw requests/responses. |
+| **Vulnerabilities** | `get_top_vulnerabilities` | Risk overview (vulnerability count by severity). |
+| **Management** | `get_projects` | List active security projects. |
+| **Management** | `get_project` | Get specific project in Conviso Platform by project ID. |
+| **Assets** | `get_assets` | List assets mapped within the platform. |
+| **Assets** | `get_asset` | Get asset in Conviso Platform by asset ID. |
+| **Utilities** | `create_issue_url` | Generates a direct link to the specific issue on the Conviso Platform. |
+| **Utilities** | `create_project_url` | Generates a direct link to the specific project on the Conviso Platform. |
+| **Utilities** | `get_today_date` | Return current day/month/year (utility). |
+| **Metrics** | `get_mttr_over_time` | Get Mean Time To Resolution (MTTR) metrics over time for a company. Returns resolution times by severity level. |
+| **Metrics** | `get_overall_risk_score_history` | Get overall risk score history for a company, including current score and difference from last period. |
+
+## 🚀 Installation and Configuration (Node.js bundle)
+
+### Prerequisites
+
+* Node.js 18 or later.
+* A Conviso Platform API Key (obtained from your profile settings).
+* An MCP-compatible client (e.g., Claude Desktop, Cursor, etc.).
+
+### Setup
+
+```bash
+git clone https://github.com/convisoappsec/conviso-mcp.git
+cd conviso-mcp/node
+npm install
+```
+
+### Run
+
+```bash
+export CONVISO_API_KEY=your_api_key_here
+npm start
+```
+
+## Staging (optional)
+
+Set the `STAGING` environment variable to `true` to make the server use
+`https://staging.convisoappsec.com` instead of the production API.
+
+Example:
+
+```bash
+# staging (testing only)
+export STAGING=true
+npm start
+```
+
+
+## Client configuration examples
+
+Below are quick examples showing how to configure Claude Desktop to run the Node bundle locally or via Docker. Paste the appropriate JSON into your Claude Desktop configuration file (see Claude docs for exact path on your OS).
+
+### A. Node.js (Local)
+
+```json
+{
+	"mcpServers": {
+		"conviso-mcp": {
+			"command": "node",
+			"args": [
+				"/ABSOLUTE/PATH/TO/REPO/node/src/conviso_mcp/server.js"
+			],
+			"env": {
+				"CONVISO_API_KEY": "your_api_key_here"
+			}
+		}
+	}
+}
+```
+
+Notes:
+- Replace `/ABSOLUTE/PATH/TO/REPO` with the absolute path to your cloned repository.
+- Ensure `node` is available in the PATH used by Claude Desktop.
+
+### B. Docker (Node bundle)
+
+```json
+{
+	"mcpServers": {
+		"conviso-mcp": {
+			"command": "docker",
+			"args": [
+				"run",
+				"-i",
+				"--rm",
+				"--init",
+				"-e",
+				"CONVISO_API_KEY=your_api_key_here",
+				"conviso-mcp-node-image"
+			]
+		}
+	}
+}
+```
+
+Notes:
+- Build the Docker image first (example):
+
+```bash
+cd node
+docker build -t conviso-mcp-node-image .
+```
+
+---
+
+## Privacy
+
+This bundle references the project's privacy policy. See `node/manifest.json` privacy_policies for details.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@convisoappsec/mcp",
+  "version": "0.3.0",
+  "description": "MCP Server for Conviso Platform integration",
+  "type": "module",
+  "main": "src/conviso_mcp/server.js",
+  "scripts": {
+    "start": "node src/conviso_mcp/server.js",
+    "dev": "node src/conviso_mcp/server.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "bin": {
+    "conviso-mcp": "src/conviso_mcp/server.js"
+  },
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/convisoappsec/conviso-mcp.git"
+  },
+  "keywords": [
+    "appsec",
+    "mcp",
+    "llm",
+    "ai"
+  ],
+  "author": {
+    "name": "Conviso",
+    "url": "https://github.com/convisoappsec"
+  },
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/convisoappsec/conviso-mcp/issues"
+  },
+  "homepage": "https://github.com/convisoappsec/conviso-mcp#readme",
+  "dependencies": {
+    "@hono/node-server": "^1.19.11",
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "axios": "^1.13.5",
+    "dotenv": "^16.6.1",
+    "zod": "^4.3.6"
+  }
+}

package/src/conviso_mcp/feed_gateway.js

@@ -0,0 +1,80 @@
+import 'dotenv/config';
+import { GraphQLClient } from './graphql_client.js';
+
+class FeedGateway {
+  constructor(graphql_api_key = '') {
+    this.base_url = 'https://app.convisoappsec.com';
+    const apiKey = process.env.CONVISO_API_KEY || graphql_api_key || '';
+    this.graphql = new GraphQLClient(`${this.base_url}/graphql`, apiKey);
+  }
+
+  async get_companies(page = 1, limit = 10, search = '') {
+    return this.graphql.get_companies(page, limit, search);
+  }
+
+  async get_company_by_id(company_id) {
+    return this.graphql.get_company_by_id(company_id);
+  }
+
+  async get_issue_by_id(issue_id, return_snippets = false) {
+    return this.graphql.get_issue_by_id(issue_id, return_snippets);
+  }
+
+  async get_issues(company_id, search = '', page = 1, limit = 1, project_id = null) {
+    return this.graphql.get_issues(company_id, search, page, limit, project_id);
+  }
+
+  async get_issue_with_company_id(company_id, issue_id) {
+    return this.graphql.get_issues(company_id, '', 1, 5, null, [issue_id]);
+  }
+
+  async get_issues_by_asset_ids(company_id, page = 1, limit = 1, asset_ids = []) {
+    return this.graphql.get_issues(company_id, '', page, limit, null, [], asset_ids);
+  }
+
+  async get_projects(company_id, page = 1, limit = 1000, search = '') {
+    return this.graphql.get_projects(company_id, page, limit, search);
+  }
+
+  async get_project_by_id(project_id) {
+    return this.graphql.get_project_by_id(project_id);
+  }
+
+  async get_assets(company_id, page = 1, limit = 1000) {
+    return this.graphql.get_assets_by_company(company_id, page, limit);
+  }
+
+  async get_asset_by_id(asset_id) {
+    return this.graphql.get_asset_by_id(asset_id);
+  }
+
+  async get_top_vulnerabilities(company_id) {
+    return this.graphql.get_top_vulnerabilities(company_id);
+  }
+
+  async generate_project_report(project_id, language = 'en', vulnerability_criticity = null, vulnerability_statuses = null, requirements = true, evidences = true) {
+    return this.graphql.generate_project_report(project_id, language, vulnerability_criticity, vulnerability_statuses, requirements, evidences);
+  }
+
+  async generate_project_report_progress(project_id, report_id) {
+    return this.graphql.generate_project_report_progress(project_id, report_id);
+  }
+
+  create_project_url(company_id, project_id) {
+    return `${this.base_url}/spa/company/${company_id}/projects/${project_id}`;
+  }
+
+  create_issue_url(company_id, issue_id) {
+    return `${this.base_url}/spa/company/${company_id}/vulnerabilities?title=&search=${issue_id}`;
+  }
+
+  async get_mttr_over_time(company_id, start_date, end_date, severities = null, statuses = null, asset_ids = null, asset_tags = null) {
+    return this.graphql.get_mttr_over_time(company_id, start_date, end_date, severities, statuses, asset_ids, asset_tags);
+  }
+
+  async get_overall_risk_score_history(company_id) {
+    return this.graphql.get_overall_risk_score_history(company_id);
+  }
+}
+
+export { FeedGateway };

package/src/conviso_mcp/graphql_client.js

@@ -0,0 +1,535 @@
+import axios from 'axios';
+
+const GraphQLFieldTemplates = {
+  complete_issue: `
+        id
+        title
+        description
+        status
+        severity
+        createdAt
+        updatedAt
+        category
+        patterns
+        reference
+        permittedStatus
+        statusHistory {
+            status
+            createdAt
+        }
+        asset {
+            id
+            name
+        }
+        project {
+            id
+            label
+
+            company {
+                id
+            }
+        }
+        author {
+            id
+            name
+            email
+        }
+`,
+
+  complete_issue_with_snippet: null,
+
+  project: `
+        id
+        label
+        status
+        createdAt
+        startDate
+        endDate
+        allocatedAnalyst {
+            portalUser {
+                name
+            }
+        }
+        projectType {
+            label
+        }
+
+        company {
+            id
+        }
+`
+};
+
+GraphQLFieldTemplates.complete_issue_with_snippet = `
+    ${GraphQLFieldTemplates.complete_issue}
+    ... on FindingInterface {
+      severity
+      solution
+      scanSource
+      originalIssueIdFromTool
+    }
+    ... on VulnerabilityInterface {
+      severity
+      impactDescription
+      solution
+      summary
+      stepsToReproduce
+      impactLevel
+      probabilityLevel
+      compromisedEnvironment
+    }
+    ... on DastFinding {
+      detail {
+        url
+        port
+        scheme
+        method
+        request
+        response
+      }
+    }
+    ... on WebVulnerability {
+      detail {
+        url
+        port
+        scheme
+        method
+        request
+        response
+        parameters
+      }
+    }
+    ... on SourceCodeVulnerability {
+      detail {
+        codeSnippet
+        fileName
+        vulnerableLine
+        firstLine
+        source
+        sink
+      }
+    }
+    ... on NetworkVulnerability {
+      detail {
+        address
+        port
+        protocol
+        attackVector
+      }
+    }
+    ... on ScaFinding {
+      detail {
+        affectedVersion
+        package
+        patchedVersion
+        cve
+        cvssScore
+        cvssMetric
+        fileName
+      }
+    }
+    ... on SastFinding {
+      detail {
+        codeSnippet
+        fileName
+        vulnerableLine
+        firstLine
+      }
+    }
+    ... on IacFinding {
+      detail {
+        codeSnippet
+        fileName
+        vulnerableLine
+        firstLine
+      }
+    }
+    ... on SecretFinding {
+      detail {
+        codeSnippet
+        fileName
+        vulnerableLine
+        firstLine
+      }
+    }
+    ... on ContainerFinding {
+      detail {
+        affectedVersion
+        package
+        patchedVersion
+        cve
+      }
+    }
+`;
+
+class GraphQLClient {
+  constructor(endpoint, apiKey) {
+    this.endpoint = endpoint;
+    this.headers = {
+      'Content-Type': 'application/json'
+    };
+    if (apiKey) {
+      this.headers['X-Api-Key'] = `${apiKey}`;
+    }
+  }
+
+  async execute(query, variables = {}) {
+    const payload = { query, variables };
+
+    let response;
+
+    try {
+      response = await axios.post(this.endpoint, payload, { headers: this.headers });
+    } catch (err) {
+      if (err.response) {
+        const e = new Error('GraphQL request failed');
+        e.status = err.response.status;
+        throw e;
+      }
+
+      if (err.code === 'ECONNREFUSED') {
+        const e = new Error('Upstream service unavailable');
+        e.status = 503;
+        throw e;
+      }
+
+      if (err.code === 'ETIMEDOUT') {
+        const e = new Error('Upstream request timeout');
+        e.status = 504;
+        throw e;
+      }
+
+      throw err;
+    }
+
+    if (response.data?.errors) {
+      const e = new Error('GraphQL error');
+      e.status = 400;
+      throw e;
+    }
+
+    return response.data.data;
+  }
+
+  async get_issues(company_id, search, page = 1, limit = 1, project_id = null, issue_ids = [], asset_ids = []) {
+    const query = `
+        query GetIssues($companyId: ID!, $pagination: PaginationInput!, $filters: IssuesFiltersInput) {
+            issues(companyId: $companyId,  pagination: $pagination, filters: $filters) {
+                collection {
+                    id
+                    title
+                    severity
+                    project {
+                        company {
+                            id
+                        }
+                    }
+
+                    asset {
+                        id
+                    }
+                }
+            }
+        }
+        `;
+
+    const variables = {
+      companyId: company_id,
+      filters: { title: search },
+      pagination: { page: page, perPage: limit }
+    };
+
+    if (project_id !== null && project_id !== 0) {
+      variables.filters.projectIds = [project_id];
+    }
+    if (Array.isArray(issue_ids) && issue_ids.length > 0) {
+      variables.filters.ids = issue_ids;
+    }
+    if (Array.isArray(asset_ids) && asset_ids.length > 0) {
+      variables.filters.assetIds = asset_ids;
+    }
+
+    return this.execute(query, variables);
+  }
+
+  async get_issue_by_id(issue_id, return_snippets = false) {
+    let query = `
+        query GetIssue($id: ID!) {
+            issue(id: $id) {
+                %s
+            }
+        }
+        `;
+    query = query.replace('%s', return_snippets ? GraphQLFieldTemplates.complete_issue_with_snippet : GraphQLFieldTemplates.complete_issue);
+    const variables = { id: issue_id };
+    return this.execute(query, variables);
+  }
+
+  async get_companies(page = 1, limit = 10, search = '') {
+    const query = `
+        query companies($page: Int, $limit: Int, $params: CompanySearch, $order: OrderScopesParams, $orderType: OrderParams){
+            companies(page: $page, limit: $limit, params: $params, order: $order, orderType : $orderType) {
+                collection {
+                    id
+                    label
+                }
+            }
+        }
+        `;
+    const variables = { page, limit, params: { labelCont: search } };
+    return this.execute(query, variables);
+  }
+
+  async get_projects(company_id, page = 1, limit = 1000, search = '') {
+    const query = `
+        query projects($page: Int, $limit: Int, $params: ProjectSearch, $sortBy: String, $descending: Boolean){
+            projects(page: $page, limit: $limit, params: $params, sortBy: $sortBy, descending : $descending) {
+                collection {
+                    id
+                    label
+                    status
+                    createdAt
+                    startDate
+                    endDate
+                    allocatedAnalyst {
+                        portalUser {
+                            name
+                        }
+                    }
+                    projectType {
+                        label
+                    }
+
+                    company {
+                        id
+                    }
+                }
+            }
+        }
+        `;
+    const variables = {
+      page,
+      limit,
+      params: { scopeIdEq: company_id, labelCont: search },
+      sortBy: 'createdAt',
+      descending: true
+    };
+    return this.execute(query, variables);
+  }
+
+  async get_project_by_id(project_id) {
+    const query = `
+        query GetProject($id: ID!) {
+            project(id: $id) {
+                ${GraphQLFieldTemplates.project}
+            }
+        }
+        `;
+    const variables = { id: project_id };
+    return this.execute(query, variables);
+  }
+
+  async get_company_by_id(company_id) {
+    const query = `
+        query Company($id: ID!) {
+        company(id: $id) {
+            id
+            label
+            sid
+            brandUrl
+            brandId
+            brandFilename
+            brandSize
+            customFeatures
+            integrations
+            createdAt
+            updatedAt
+            configured
+            companyPlan {
+            name
+            id
+            }
+        }
+        }
+        `;
+    const variables = { id: company_id };
+    return this.execute(query, variables);
+  }
+
+  async get_assets_by_company(company_id, page = 1, limit = 10) {
+    const query = `
+        query ListAssets($companyId: ID!, $page: Int, $limit: Int) {
+            assets(companyId: $companyId, page: $page, limit: $limit) {
+                collection {
+                    id
+                    name
+                    assetType
+                    environment
+                    audience
+                    createdAt
+                    updatedAt
+                }
+                metadata {
+                    totalCount
+                    totalPages
+                    currentPage
+                    limitValue
+                }
+            }
+        }
+        `;
+    const variables = { companyId: company_id, page, limit };
+    return this.execute(query, variables);
+  }
+
+  async get_asset_by_id(asset_id) {
+    const query = `
+        query asset($id: ID!) {
+            asset(id: $id) {
+                id
+                name
+                assetType
+                businessImpact
+                architectureType
+                technologies
+                environment
+                audience
+                description
+                createdAt
+                updatedAt
+                company {
+                    id
+                }
+                riskScore{
+                    current{
+                        value
+                    }
+                }
+            }
+        }
+        `;
+    const variables = { id: asset_id };
+    return this.execute(query, variables);
+  }
+
+  async get_top_vulnerabilities(company_id) {
+    const query = `
+        query TopVulnerabilities($companyId: ID!) {
+            topVulnerabilities(companyId: $companyId) {
+                affectedAssetsCount
+                criticalCount
+                highCount
+                lowCount
+                mediumCount
+                title
+                totalCount
+            }
+        }
+        `;
+    const variables = { companyId: company_id };
+    return this.execute(query, variables);
+  }
+
+  async get_mttr_over_time(company_id, start_date, end_date, severities = null, statuses = null, asset_ids = null, asset_tags = null) {
+    const query = `
+        query MttrOverTime($companyId: ID!, $params: FilterParams!) {
+            mttrOverTime(companyId: $companyId, params: $params) {
+                all
+                critical
+                dates
+                high
+                low
+                medium
+                notification
+            }
+        }
+        `;
+    const variables = {
+      companyId: company_id,
+      params: {
+        startDate: start_date,
+        endDate: end_date,
+        severities: severities || ["NOTIFICATION", "LOW", "MEDIUM", "HIGH", "CRITICAL"],
+        statuses: statuses || ["CREATED", "DRAFT", "IDENTIFIED", "IN_PROGRESS", "AWAITING_VALIDATION", "FIX_ACCEPTED", "RISK_ACCEPTED", "FALSE_POSITIVE", "SUPPRESSED"],
+        assetIds: asset_ids || [],
+        assetTags: asset_tags || []
+      }
+    };
+    return this.execute(query, variables);
+  }
+
+  async get_overall_risk_score_history(company_id) {
+    const query = `
+        query OverallRiskScoreHistory($companyId: ID!) {
+            overallRiskScoreHistory(companyId: $companyId) {
+                company {
+                    id
+                    label
+                }
+                current {
+                    date
+                    value
+                }
+                differenceFromLast {
+                    date
+                    value
+                }
+            }
+        }
+        `;
+    const variables = { companyId: company_id };
+    return this.execute(query, variables);
+  }
+
+  async generate_project_report(project_id, language = 'en', vulnerability_criticity = null, vulnerability_statuses = null, requirements = true, evidences = true) {
+    const query = `
+        query GenerateProjectReport(
+            $projectId: ID!,
+            $language: String!,
+            $vulnerabilityCriticity: [SeverityCategory!],
+            $vulnerabilityStatuses: [IssueStatusLabel!],
+            $requirements: Boolean!,
+            $evidences: Boolean!
+        ) {
+            generateProjectReport(
+                projectId: $projectId,
+                language: $language,
+                vulnerabilityCriticity: $vulnerabilityCriticity,
+                vulnerabilityStatuses: $vulnerabilityStatuses,
+                requirements: $requirements,
+                evidences: $evidences
+            ) {
+                id
+                reportUrl
+                status
+            }
+        }
+        `;
+    const variables = {
+      projectId: project_id,
+      language,
+      vulnerabilityCriticity: vulnerability_criticity || ["CRITICAL", "HIGH", "MEDIUM", "LOW", "NOTIFICATION"],
+      vulnerabilityStatuses: vulnerability_statuses || ["IDENTIFIED", "IN_PROGRESS", "AWAITING_VALIDATION", "FIX_ACCEPTED", "RISK_ACCEPTED", "FALSE_POSITIVE"],
+      requirements,
+      evidences
+    };
+    return this.execute(query, variables);
+  }
+
+  async generate_project_report_progress(project_id, report_id) {
+    const query = `
+        query GenerateProjectReport($projectId: ID!, $reportId: ID!) {
+            projectReport(projectId: $projectId, reportId: $reportId) {
+                id
+                progress
+                reportUrl
+                status
+            }
+        }
+        `;
+    const variables = { projectId: project_id, reportId: report_id };
+    return this.execute(query, variables);
+  }
+}
+
+export { GraphQLClient };

package/src/conviso_mcp/server.js

@@ -0,0 +1,438 @@
+#!/usr/bin/env node
+
+import 'dotenv/config';
+import http from 'node:http';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { z } from 'zod';
+
+import { FeedGateway } from './feed_gateway.js';
+import pkg from '../../package.json' with { type: 'json' };
+
+const gateway = new FeedGateway();
+
+console.error('[+] Starting Conviso MCP Server (MCP SDK)');
+
+const server = new McpServer({
+  name: pkg.name || 'conviso-mcp',
+  version: pkg.version || '0.3.0',
+});
+
+function sanitizeError(err, message = 'Request failed') {
+  const error_id = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+
+  const status =
+    err?.response?.status ??
+    err?.response?.statusCode ??
+    err?.status ??
+    err?.statusCode ??
+    (err?.code === 'ECONNREFUSED' ? 503 : undefined) ??
+    (err?.code === 'ETIMEDOUT' ? 504 : undefined) ??
+    500;
+
+  console.error('[tool_error]', {
+    error_id,
+    name: err?.name,
+    code: err?.code,
+    message: err?.message?.slice(0, 200),
+    status,
+  });
+
+  return { error: message, status, error_id };
+}
+
+function ok(data) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: typeof data === 'string' ? data : JSON.stringify(data),
+      },
+    ],
+  };
+}
+
+function fail(err, msg) {
+  return ok(sanitizeError(err, msg));
+}
+
+server.registerTool(
+  'get_companies',
+  {
+    description: 'Return a paginated list of companies accessible with the provided API key. Use `search` to filter by company name.',
+    inputSchema: z.object({
+      page: z.number().optional(),
+      limit: z.number().optional(),
+      search: z.string().optional(),
+    }),
+    annotations: {
+      title: 'List Companies',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ page = 1, limit = 10, search = '' }) => {
+    try {
+      return ok(await gateway.get_companies(page, limit, search));
+    } catch (err) {
+      return fail(err, 'Failed to list companies');
+    }
+  }
+);
+
+server.registerTool(
+  'get_company_info',
+  {
+    description: 'Retrieve detailed information about a specific company, including plan, integrations, and branding metadata.',
+    inputSchema: z.object({ company_id: z.number() }),
+    annotations: {
+      title: 'Company Details',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id }) => {
+    try {
+      return ok(await gateway.get_company_by_id(company_id));
+    } catch (err) {
+      return fail(err, 'Failed to get company info');
+    }
+  }
+);
+
+server.registerTool(
+  'get_issue',
+  {
+    description: 'Fetch detailed technical data for a specific vulnerability/issue. Optionally include raw request/response and vulnerable code snippets when `return_vulnerable_data` is true. WARNING: setting `return_vulnerable_data=true` may return sensitive data (exploit code, raw HTTP requests/responses, or secrets) — use with caution.',
+    inputSchema: z.object({
+      id: z.number(),
+      return_vulnerable_data: z.boolean().optional(),
+    }),
+    annotations: {
+      title: 'Issue Details',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ id, return_vulnerable_data }) => {
+    try {
+      return ok(await gateway.get_issue_by_id(id, return_vulnerable_data));
+    } catch (err) {
+      return fail(err, 'Failed to get issue details');
+    }
+  }
+);
+
+server.registerTool(
+  'get_issues',
+  {
+    description: 'List vulnerabilities for a company or project.',
+    inputSchema: z.object({
+      company_id: z.number(),
+      page: z.number().optional(),
+      limit: z.number().optional(),
+      project_id: z.number().optional(),
+    }),
+    annotations: {
+      title: 'List Issues',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id, page = 1, limit = 10, project_id }) => {
+    try {
+      return ok(await gateway.get_issues(company_id, '', page, limit, project_id));
+    } catch (err) {
+      return fail(err, 'Failed to list issues');
+    }
+  }
+);
+
+server.registerTool(
+  'get_top_vulnerabilities',
+  {
+    description: 'Return a summary of vulnerability counts grouped by severity for a given company (risk overview).',
+    inputSchema: z.object({ company_id: z.number() }),
+    annotations: {
+      title: 'Top Vulnerabilities',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id }) => {
+    try {
+      return ok(await gateway.get_top_vulnerabilities(company_id));
+    } catch (err) {
+      return fail(err, 'Failed to get top vulnerabilities');
+    }
+  }
+);
+
+server.registerTool(
+  'get_projects',
+  {
+    description: 'Return a paginated list of active security projects for a company. Defaults to 25 results per page to conserve tokens.',
+    inputSchema: z.object({
+      company_id: z.number(),
+      page: z.number().optional(),
+      limit: z.number().optional(),
+      search: z.string().optional(),
+    }),
+    annotations: {
+      title: 'List Projects',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id, page = 1, limit = 25, search = '' }) => {
+    try {
+      return ok(await gateway.get_projects(company_id, page, limit, search));
+    } catch (err) {
+      return fail(err, 'Failed to list projects');
+    }
+  }
+);
+
+server.registerTool(
+  'get_project',
+  {
+    description: 'Retrieve detailed metadata for a specific project by its ID.',
+    inputSchema: z.object({ project_id: z.number() }),
+    annotations: {
+      title: 'Project Details',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ project_id }) => {
+    try {
+      return ok(await gateway.get_project_by_id(project_id));
+    } catch (err) {
+      return fail(err, 'Failed to get project');
+    }
+  }
+);
+
+server.registerTool(
+  'get_asset',
+  {
+    description: 'Fetch information about a specific asset by its ID.',
+    inputSchema: z.object({ asset_id: z.number() }),
+    annotations: {
+      title: 'Asset Details',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ asset_id }) => {
+    try {
+      return ok(await gateway.get_asset_by_id(asset_id));
+    } catch (err) {
+      return fail(err, 'Failed to get asset');
+    }
+  }
+);
+
+server.registerTool(
+  'get_assets',
+  {
+    description: 'Return a paginated list of assets for a company. Defaults to 25 results per page to reduce token usage.',
+    inputSchema: z.object({
+      company_id: z.number(),
+      page: z.number().optional(),
+      limit: z.number().optional(),
+    }),
+    annotations: {
+      title: 'List Assets',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id, page = 1, limit = 25 }) => {
+    try {
+      return ok(await gateway.get_assets(company_id, page, limit));
+    } catch (err) {
+      return fail(err, 'Failed to list assets');
+    }
+  }
+);
+
+server.registerTool(
+  'create_project_url',
+  {
+    description: 'Return a direct URL to open a project in the Conviso Platform for quick navigation.',
+    inputSchema: z.object({
+      company_id: z.number(),
+      project_id: z.number(),
+    }),
+    annotations: {
+      title: 'Project URL Generator',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id, project_id }) => {
+    try {
+      return ok(await gateway.create_project_url(company_id, project_id));
+    } catch (err) {
+      return fail(err, 'Failed to create project URL');
+    }
+  }
+);
+
+server.registerTool(
+  'create_issue_url',
+  {
+    description: 'Return a direct URL to open a specific issue in the Conviso Platform for triage or review.',
+    inputSchema: z.object({
+      company_id: z.number(),
+      issue_id: z.number(),
+    }),
+    annotations: {
+      title: 'Issue URL Generator',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id, issue_id }) => {
+    try {
+      return ok(await gateway.create_issue_url(company_id, issue_id));
+    } catch (err) {
+      return fail(err, 'Failed to create issue URL');
+    }
+  }
+);
+
+server.registerTool(
+  'get_mttr_over_time',
+  {
+    description: 'Get Mean Time To Resolution (MTTR) aggregated over a date range. Supports filtering by severities, statuses, and assets.',
+    inputSchema: z.object({
+      company_id: z.number(),
+      start_date: z.string(),
+      end_date: z.string(),
+      severities: z.array(z.string()).optional(),
+      statuses: z.array(z.string()).optional(),
+      asset_ids: z.array(z.number()).optional(),
+      asset_tags: z.array(z.string()).optional(),
+    }),
+    annotations: {
+      title: 'MTTR Over Time',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async (args) => {
+    try {
+      return ok(await gateway.get_mttr_over_time(
+        args.company_id,
+        args.start_date,
+        args.end_date,
+        args.severities,
+        args.statuses,
+        args.asset_ids,
+        args.asset_tags
+      ));
+    } catch (err) {
+      return fail(err, 'Failed to get MTTR metrics');
+    }
+  }
+);
+
+server.registerTool(
+  'get_overall_risk_score_history',
+  {
+    description: 'Retrieve historical overall risk scores for a company, useful for trend analysis and reporting.',
+    inputSchema: z.object({
+      company_id: z.number(),
+    }),
+    annotations: {
+      title: 'Risk Score History',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true,
+    },
+  },
+  async ({ company_id }) => {
+    try {
+      return ok(await gateway.get_overall_risk_score_history(company_id));
+    } catch (err) {
+      return fail(err, 'Failed to get risk score history');
+    }
+  }
+);
+
+server.registerTool(
+  'get_today_date',
+  {
+    description: 'Utility tool returning the current date.',
+    inputSchema: z.object({}),
+    annotations: {
+      title: 'Get Today Date',
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false,
+    },
+  },
+  async () => {
+    try {
+      const d = new Date();
+      return ok({ day: d.getDate(), month: d.getMonth() + 1, year: d.getFullYear() });
+    } catch (err) {
+      return fail(err, 'Failed to get current date');
+    }
+  }
+);
+
+/**
+ * START
+ */
+
+const PORT = process.env.PORT ? parseInt(process.env.PORT, 10) : null;
+
+if (PORT) {
+  const httpServer = http.createServer(async (req, res) => {
+    if (req.method !== 'POST' && req.method !== 'GET' && req.method !== 'DELETE') {
+      res.writeHead(405).end();
+      return;
+    }
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    await server.connect(transport);
+    await transport.handleRequest(req, res);
+  });
+
+  httpServer.listen(PORT, () => {
+    console.error(`Conviso MCP Server running on HTTP port ${PORT}`);
+  });
+} else {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Conviso MCP Server running on stdio');
+}