@convisoappsec/mcp 0.6.3 → 0.7.0

package/README.md

@@ -25,12 +25,13 @@ The server exposes the following tools to the LLM (see `node/manifest.json` for
 | **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. |
 | **Tickets** | `get_tickets` / `get_ticket` | List or fetch support/bug tickets. |
-| **Requirements** | `get_requirements` / `get_requirement` / `get_project_requirements` | Browse security requirements/checklists. |
+| **Requirements** | `get_requirements` / `get_requirement` / `get_project_requirements` / `get_project_requirement_activities` | Browse requirements/checklists and the instantiated activities of a requirement within a project. When only the project is known, use `get_project_requirements` first to discover the required `project_requirement_id`. |
 | **Applications** | `get_applications` / `get_application` | List or fetch applications and their assets. |
 | **Scans** | `get_scan_histories` / `get_asset_scans_count` | Scan execution history and coverage counts. |
 | **Supply chain** | `get_sbom_components` | SBOM / dependency components per company. |
 | **AI-Pentest** | `get_pentest_artifacts` / `get_pentest_artifact` / `get_pentest_execution` | Pentest artifacts, scope and execution results. |
 | **Threat Modeling** | `get_threat_model_artifacts` / `get_threat_model_artifact` | Threat model artifacts and versions. |
+| **Utilities** | `get_company_id_from_object` | Resolve the owning company from an issue, asset, project, pentest or threat-model object ID before a write. |
 | **Writes — engine** | `list_mutations` / `describe_mutation` / `execute_mutation` | Discover, describe and run the permitted write operations below. |
 | **Writes — Issues** | `execute_mutation` | Create, update, delete and change status of vulnerabilities/issues. |
 | **Writes — Assets** | `execute_mutation` | Create and update assets; run a DAST scan. |

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "@convisoappsec/mcp",
-  "version": "0.6.3",
-  "mcpName": "io.github.convisoappsec/conviso-mcp",
+  "version": "0.7.0",
   "description": "MCP Server for Conviso Platform integration",
   "type": "module",
   "main": "src/conviso_mcp/server.js",

package/src/conviso_mcp/graphql_client.js

@@ -454,6 +454,29 @@ export function buildProjectsVariables(companyId, page = 1, limit = 1000, opts =
   return { page, limit, params, sortBy, descending };
 }
 
+export function buildProjectRequirementActivitiesVariables(projectId, projectRequirementId, {
+  page = 1,
+  limit = 10,
+  title = '',
+  sortBy = 'SORT',
+  descending = false,
+  attachmentActionsOnly,
+} = {}) {
+  return {
+    page,
+    limit,
+    sortBy,
+    descending,
+    historyPagination: { page: 1, perPage: limit },
+    attachmentActionsOnly,
+    params: compact({
+      projectId,
+      projectRequirementId,
+      title,
+    }),
+  };
+}
+
 // Shared HTTP client: keep-alive reuses the TLS connection across the many sequential
 // calls an agent session makes; the timeout stops a hung upstream from hanging a tool
 // call (and the MCP client) forever.
@@ -463,6 +486,16 @@ const httpClient = axios.create({
 });
 
 const RETRYABLE_STATUS = new Set([429, 502, 503]);
+const MCP_WRITE_POLICY_FIELD_MISSING =
+  "Field 'enableMcpWrite' doesn't exist on type 'PolicyControls'";
+
+const MCP_WRITE_POLICY_QUERY = `
+  query McpWritePolicy($companyId: ID!) {
+    policyControls(companyId: $companyId) {
+      enableMcpWrite
+    }
+  }
+`;
 
 class GraphQLClient {
   constructor(endpoint, apiKey) {
@@ -488,6 +521,82 @@ class GraphQLClient {
     }
   }
 
+  async assertMcpWriteEnabled(companyId) {
+    if (companyId === undefined || companyId === null) {
+      const error = new Error('Could not determine company for MCP write policy check');
+      error.status = 400;
+      throw error;
+    }
+    let data;
+    try {
+      data = await this.execute(MCP_WRITE_POLICY_QUERY, { companyId });
+    } catch (error) {
+      // Older backends do not expose the policy field yet. Their effective default is
+      // enabled, matching the backend default once the field becomes available.
+      const fieldNotDeployed = error.graphqlErrors?.some((message) =>
+        message.startsWith(MCP_WRITE_POLICY_FIELD_MISSING));
+      if (fieldNotDeployed) return;
+      throw error;
+    }
+    if (data?.policyControls?.enableMcpWrite !== true) {
+      const error = new Error(`MCP write operations are disabled by company ${companyId} policy`);
+      error.status = 403;
+      // Explicitly safe to return to the MCP caller. Other upstream errors stay sanitized.
+      error.publicMessage = error.message;
+      error.authHint = `Enable MCP write operations in the policy controls for company ${companyId}`;
+      throw error;
+    }
+  }
+
+  async getCompanyIdFromObject(objectType, objectId) {
+    // This is deliberately an object inventory, not a mutation inventory. It gives the
+    // model an explicit read step when a user supplies an entity ID but no company ID.
+    const lookups = {
+      issue: {
+        query: 'issue(id: $id) { asset { company { id } } }',
+        companyId: (data) => data?.issue?.asset?.company?.id,
+      },
+      asset: {
+        query: 'asset(id: $id) { company { id } }',
+        companyId: (data) => data?.asset?.company?.id,
+      },
+      project: {
+        query: 'project(id: $id) { company { id } }',
+        companyId: (data) => data?.project?.company?.id,
+      },
+      pentest_artifact: {
+        query: 'pentestArtifact(id: $id) { company { id } }',
+        companyId: (data) => data?.pentestArtifact?.company?.id,
+      },
+      pentest_execution: {
+        query: 'pentestExecution(id: $id) { project { company { id } } }',
+        companyId: (data) => data?.pentestExecution?.project?.company?.id,
+      },
+      threat_model_artifact: {
+        query: 'threatModelArtifact(id: $id) { company { id } }',
+        companyId: (data) => data?.threatModelArtifact?.company?.id,
+      },
+    };
+    const lookup = lookups[objectType];
+    if (!lookup) {
+      const error = new Error(`Unsupported object type '${objectType}'`);
+      error.status = 400;
+      throw error;
+    }
+    const data = await this.execute(`
+      query CompanyFromObject($id: ID!) {
+        ${lookup.query}
+      }
+    `, { id: objectId });
+    const companyId = lookup.companyId(data);
+    if (companyId === undefined || companyId === null) {
+      const error = new Error(`Could not find a company for ${objectType} '${objectId}'`);
+      error.status = 404;
+      throw error;
+    }
+    return { object_type: objectType, object_id: objectId, company_id: Number(companyId) };
+  }
+
   async #post(query, variables) {
     let response;
     try {
@@ -825,6 +934,36 @@ class GraphQLClient {
     return this.execute(query, { projectId: project_id });
   }
 
+  async get_project_requirement_activities(project_id, project_requirement_id, options = {}) {
+    const query = `
+      query GetProjectRequirementActivities(
+        $page: Int
+        $limit: Int
+        $sortBy: ActivitySortByEnum
+        $descending: Boolean
+        $historyPagination: PaginationInput!
+        $attachmentActionsOnly: Boolean
+        $params: ActivitiesSearch!
+      ) {
+        activities(page: $page, limit: $limit, params: $params, sortBy: $sortBy, descending: $descending) {
+          collection {
+            id title status permittedStatus description reference updatedAt reason
+            history(pagination: $historyPagination, attachmentActionsOnly: $attachmentActionsOnly) {
+              metadata { totalCount }
+            }
+            portalUser { avatarUrl email name }
+            check { description id label }
+            assignedUsers { avatarUrl name email }
+          }
+          metadata { currentPage limitValue totalCount totalPages }
+        }
+      }`;
+    return this.execute(
+      query,
+      buildProjectRequirementActivitiesVariables(project_id, project_requirement_id, options),
+    );
+  }
+
   async get_applications(company_id, search = null) {
     const query = `
       query GetApplications($companyId: ID!, $search: String) {

package/src/conviso_mcp/server.js

@@ -36,7 +36,9 @@ function sanitizeError(err, message = 'Request failed') {
     status,
   });
 
-  const result = { error: message, status, error_id };
+  // Only errors deliberately marked by our own code may override the generic tool error.
+  // Never expose arbitrary upstream messages here.
+  const result = { error: err?.publicMessage || message, status, error_id };
   // GraphQL errors describe the caller's own request (e.g. a missing required field) — pass
   // them through so the model can fix the input on the next attempt.
   if (Array.isArray(err?.graphqlErrors) && err.graphqlErrors.length) {
@@ -62,6 +64,7 @@ function ok(data) {
 // Shared enum strings so tool descriptions state each list exactly once.
 const SEVERITIES = 'NOTIFICATION, LOW, MEDIUM, HIGH, CRITICAL';
 const ISSUE_STATUSES = 'CREATED, DRAFT, IDENTIFIED, IN_PROGRESS, AWAITING_VALIDATION, FIX_ACCEPTED, RISK_ACCEPTED, FALSE_POSITIVE, SUPPRESSED';
+const COMPANY_OBJECT_TYPES = ['issue', 'asset', 'project', 'pentest_artifact', 'pentest_execution', 'threat_model_artifact'];
 
 /**
  * Build a fresh McpServer with all tools registered. stdio mode uses one instance for the
@@ -75,7 +78,10 @@ function buildServer() {
   });
 
   // Registration helper: one place for the try/catch, error shape, and annotations.
-  function tool(name, { title, desc, schema, write = false, destructive = false, local = false }, handler) {
+  function tool(name, {
+    title, desc, schema, write = false, destructive = false, local = false,
+    policy = write, companyId = (args) => args.company_id,
+  }, handler) {
     server.registerTool(
       name,
       {
@@ -91,6 +97,8 @@ function buildServer() {
       },
       async (args) => {
         try {
+          const checkPolicy = typeof policy === 'function' ? policy(args) : policy;
+          if (checkPolicy) await gql.assertMcpWriteEnabled(await companyId(args));
           return ok(await handler(args));
         } catch (err) {
           return ok(sanitizeError(err, `${name} failed`));
@@ -121,6 +129,15 @@ function buildServer() {
     schema: z.object({ company_id: z.number() }),
   }, ({ company_id }) => gql.get_company_by_id(company_id));
 
+  tool('get_company_id_from_object', {
+    title: 'Resolve Company from Object',
+    desc: `Resolve the company_id that owns an existing Conviso object. IMPORTANT: mutation tools require company_id for the MCP write-policy check. When the user asks for a write and provides only an object ID (for example issue_id, asset_id, project_id, pentest artifact/execution ID, or threat-model artifact ID), call this tool first with the matching object_type, then pass the returned company_id to the mutation tool. Do not guess a company_id and do not pass the object ID as company_id. Supported object_type values: ${COMPANY_OBJECT_TYPES.join(', ')}. This lookup is for write preparation; it does not perform a mutation.`,
+    schema: z.object({
+      object_type: z.enum(COMPANY_OBJECT_TYPES),
+      object_id: z.number(),
+    }),
+  }, ({ object_type, object_id }) => gql.getCompanyIdFromObject(object_type, object_id));
+
   tool('get_issue', {
     title: 'Issue Details',
     desc: 'Get full technical detail for one issue/vulnerability. Set return_vulnerable_data=true to include raw requests/responses and vulnerable code snippets (may contain sensitive data).',
@@ -383,10 +400,35 @@ function buildServer() {
 
   tool('get_project_requirements', {
     title: 'Project Requirements',
-    desc: 'List the requirements/checklists attached to a project.',
+    desc: 'List the requirements/checklists attached to a project. The returned project-requirement id is the project_requirement_id used by get_project_requirement_activities. When the user knows only the project, call this tool first, choose the requested requirement from the results (ask only if ambiguous), then call get_project_requirement_activities.',
     schema: z.object({ project_id: z.number() }),
   }, ({ project_id }) => gql.get_project_requirements(project_id));
 
+  tool('get_project_requirement_activities', {
+    title: 'Project Requirement Activities',
+    desc: 'List the instantiated activities for one requirement/checklist within a project, including status, permitted transitions, assignees, references, reason, and history count. Requires the project-requirement association id, not the requirement template id. If the user provides only a project, first call get_project_requirements(project_id) to discover project_requirement_id, then call this tool for the relevant requirement; repeat for each returned requirement when the user asks for all project checklist activities.',
+    schema: z.object({
+      project_id: z.number(),
+      project_requirement_id: z.number(),
+      page: z.number().optional(),
+      limit: z.number().optional(),
+      title: z.string().optional(),
+      sort_by: z.string().optional().describe('ActivitySortByEnum value; defaults to SORT.'),
+      descending: z.boolean().optional(),
+      attachment_actions_only: z.boolean().optional(),
+    }),
+  }, ({
+    project_id, project_requirement_id, page, limit, title, sort_by,
+    descending, attachment_actions_only,
+  }) => gql.get_project_requirement_activities(project_id, project_requirement_id, {
+    page,
+    limit,
+    title,
+    sortBy: sort_by,
+    descending,
+    attachmentActionsOnly: attachment_actions_only,
+  }));
+
   tool('get_applications', {
     title: 'List Applications',
     desc: 'List a company\'s applications (name, url, riskScore, assetsCount). Optional: search by name.',
@@ -504,14 +546,16 @@ function buildServer() {
 
   tool('execute_mutation', {
     title: 'Execute Mutation',
-    desc: 'Run any permitted write operation by name (see list_mutations). variables is the mutation input — pass { input: {...} } or the input fields directly (auto-wrapped). Optional return_fields overrides the returned selection set. WARNING: performs writes; delete/bulk operations are destructive — confirm intent first.',
+    desc: 'Run any permitted write operation by name (see list_mutations). company_id is required only for the MCP write-policy check and is not added to the GraphQL mutation input. If the user supplied an object ID but no company, call get_company_id_from_object first. variables is the mutation input — pass { input: {...} } or the input fields directly (auto-wrapped). Optional return_fields overrides the returned selection set. WARNING: performs writes; delete/bulk operations are destructive — confirm intent first.',
     schema: z.object({
+      company_id: z.number(),
       name: z.string(),
       variables: z.record(z.string(), z.any()).optional(),
       return_fields: z.string().optional(),
     }),
     write: true,
     destructive: true,
+    policy: ({ name }) => name !== 'createTicket',
   }, ({ name, variables = {}, return_fields = null }) =>
     gql.executeMutation(name, variables, return_fields));
 
@@ -521,8 +565,9 @@ function buildServer() {
 
   tool('change_issue_status', {
     title: 'Change Issue Status',
-    desc: `Change an issue's status. status: one of ${ISSUE_STATUSES}. Optional reason; extra = advanced ChangeIssueStatusInput fields (e.g. riskAcceptedUntil).`,
+    desc: `Change an issue's status. Required: company_id and issue_id; if only issue_id is known, call get_company_id_from_object first. status: one of ${ISSUE_STATUSES}. Optional reason; extra = advanced ChangeIssueStatusInput fields (e.g. riskAcceptedUntil).`,
     schema: z.object({
+      company_id: z.number(),
       issue_id: z.number(),
       status: z.string(),
       reason: z.string().optional(),
@@ -533,8 +578,9 @@ function buildServer() {
 
   tool('create_source_code_vulnerability', {
     title: 'Create Source Code Vulnerability',
-    desc: `Create a manual source-code (SAST-style) vulnerability on an asset. severity: ${SEVERITIES}. impact_level/probability_level: LOW, MEDIUM, HIGH (default MEDIUM). status defaults to DRAFT. extra = any other CreateSourceCodeVulnerabilityInput field.`,
+    desc: `Create a manual source-code (SAST-style) vulnerability on an asset. Required: company_id and asset_id; if only asset_id is known, call get_company_id_from_object first. severity: ${SEVERITIES}. impact_level/probability_level: LOW, MEDIUM, HIGH (default MEDIUM). status defaults to DRAFT. extra = any other CreateSourceCodeVulnerabilityInput field.`,
     schema: z.object({
+      company_id: z.number(),
       asset_id: z.number(),
       title: z.string(),
       description: z.string(),
@@ -610,19 +656,20 @@ function buildServer() {
       extra: z.record(z.string(), z.any()).optional(),
     }),
     write: true,
+    policy: false,
   }, (a) => gql.create_ticket(a));
 
   tool('run_dast', {
     title: 'Run DAST',
-    desc: 'Start a Conviso DAST scan on an asset (startConvisoDast). Required: asset_id.',
-    schema: z.object({ asset_id: z.number(), extra: z.record(z.string(), z.any()).optional() }),
+    desc: 'Start a Conviso DAST scan on an asset (startConvisoDast). Required: company_id and asset_id. If only asset_id is known, call get_company_id_from_object first.',
+    schema: z.object({ company_id: z.number(), asset_id: z.number(), extra: z.record(z.string(), z.any()).optional() }),
     write: true,
   }, (a) => gql.run_dast(a));
 
   tool('trigger_pentest', {
     title: 'Trigger AI-Pentest',
-    desc: 'Trigger an AI-Pentest execution from an existing pentest artifact (createPentestExecution). Required: artifact_id.',
-    schema: z.object({ artifact_id: z.number(), extra: z.record(z.string(), z.any()).optional() }),
+    desc: 'Trigger an AI-Pentest execution from an existing pentest artifact (createPentestExecution). Required: company_id and artifact_id. If only artifact_id is known, call get_company_id_from_object with object_type pentest_artifact first.',
+    schema: z.object({ company_id: z.number(), artifact_id: z.number(), extra: z.record(z.string(), z.any()).optional() }),
     write: true,
   }, (a) => gql.trigger_pentest(a));