From da76127be27e93af66300085004698a464a622cd Mon Sep 17 00:00:00 2001 From: Taylor Hatfield <35178877+thatfield1@users.noreply.github.com> Date: Sat, 16 Aug 2025 07:23:22 -0500 Subject: [PATCH 01/24] Adding support for risk scenarios --- README.md | 7 +++++ src/eval/eval.ts | 9 ++++++ src/index.ts | 8 ++++++ src/operations/risks.ts | 61 +++++++++++++++++++++++++++++++++++++++++ 4 files changed, 85 insertions(+) create mode 100644 src/operations/risks.ts diff --git a/README.md b/README.md index f70c6e5..d4b3cd3 100644 --- a/README.md +++ b/README.md @@ -26,6 +26,12 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Get specific tests that validate each security control - Understand which automated tests monitor compliance for specific controls +### Risk Scenario Management + +- Get all the risk scenarios you are managing in your current risk register. +- Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. +- Filterable by risk category (Access Control, Cryptography, Privacy, and many others). + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -41,6 +47,7 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_framework_controls` | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | | `get_controls` | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | | `get_control_tests` | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | +| `get_risks` | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | ## Configuration diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 649ec6b..d3e4c45 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -9,6 +9,7 @@ import { GetControlsTool, GetControlTestsTool, } from "../operations/controls.js"; +import { GetRisksTool } from "../operations/risks.js"; // Format all tools for OpenAI const tools = [ @@ -60,6 +61,14 @@ const tools = [ parameters: zodToJsonSchema(GetControlTestsTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetRisksTool.name, + description: GetRisksTool.description, + parameters: zodToJsonSchema(GetRisksTool.parameters), + }, + }, ]; // Test cases with expected tool calls diff --git a/src/index.ts b/src/index.ts index eaaa4d1..e7cba1a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -20,6 +20,7 @@ import { getControls, getControlTests, } from "./operations/controls.js"; +import { getRisks, GetRisksTool } from "./operations/risks.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -71,6 +72,13 @@ server.tool( getControlTests, ); +server.tool( + GetRisksTool.name, + GetRisksTool.description, + GetRisksTool.parameters.shape, + getRisks, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/risks.ts b/src/operations/risks.ts new file mode 100644 index 0000000..7266dac --- /dev/null +++ b/src/operations/risks.ts @@ -0,0 +1,61 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; + +const GetRisksInput = z.object({ + pageSize: z + .number() + .optional() + .describe( + "Controls the maximum number of risks returned in a single response. Allowed values: 1–100. Default is 10.", + ), + pageCursor: z + .string() + .optional() + .describe("Used for pagination. Leave blank to start from the first page."), + categoryMatchesAny: z + .string() + .optional() + .describe( + "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc.", + ), +}); + +export const GetRisksTool: Tool = { + name: "get_risks", + description: "List all risk scenarios in your Vanta risk register.", + parameters: GetRisksInput, +}; + +export async function getRisks( + args: z.infer, +): Promise { + const url = new URL("/v1/risk-scenarios", baseApiUrl()); + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + if (args.categoryMatchesAny !== undefined) { + url.searchParams.append("categoryMatchesAny", args.categoryMatchesAny); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { type: "text" as const, text: `Error: ${response.statusText}` }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 21f105f7607603a48b3700db86e03540ef15c09d Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 11:59:12 -0400 Subject: [PATCH 02/24] Move reusable descriptions to constants file Add final GET endpoint for Tests --- README.md | 1 + src/eval/eval.ts | 6 ++++ src/global-descriptions.ts | 5 +++ src/index.ts | 9 +++++ src/operations/tests.ts | 70 ++++++++++++++++++++++++++++++-------- 5 files changed, 76 insertions(+), 15 deletions(-) create mode 100644 src/global-descriptions.ts diff --git a/README.md b/README.md index d4b3cd3..9ba9960 100644 --- a/README.md +++ b/README.md @@ -43,6 +43,7 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `get_tests` | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | | `get_test_entities` | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | +| `get_test_by_id` | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `get_tests` response or from the address bar of your browser after /tests/. | | `get_frameworks` | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | | `get_framework_controls` | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | | `get_controls` | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | diff --git a/src/eval/eval.ts b/src/eval/eval.ts index d3e4c45..43b08ce 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -106,6 +106,12 @@ const testCases: TestCase[] = [ expectedParams: { testId: "aws-security-groups-open-to-world" }, description: "Should call get_test_entities for specific test details", }, + { + prompt: "Show me the details of test ID aws-security-groups-open-to-world", + expectedTool: "get_test_by_id", + expectedParams: { testId: "aws-security-groups-open-to-world" }, + description: "Should call get_test_by_id for specific test details", + }, { prompt: "What compliance frameworks are we tracking?", expectedTool: "get_frameworks", diff --git a/src/global-descriptions.ts b/src/global-descriptions.ts new file mode 100644 index 0000000..fe628ec --- /dev/null +++ b/src/global-descriptions.ts @@ -0,0 +1,5 @@ +export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of tests returned in a single response. +Allowed values: 1–100. Default is 10.`; + +export const PAGE_CURSOR_DESCRIPTION = `A marker or pointer telling the API where to start fetching items for the +subsequent page in a paginated response. Leave blank to start from the first page.` \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index e7cba1a..118f980 100644 --- a/src/index.ts +++ b/src/index.ts @@ -7,6 +7,8 @@ import { GetTestEntitiesTool, getTests, GetTestsTool, + getTestById, + GetTestByIdTool, } from "./operations/tests.js"; import { GetFrameworkControlsTool, @@ -37,6 +39,13 @@ server.tool( getTests, ); +server.tool( + GetTestByIdTool.name, + GetTestByIdTool.description, + GetTestByIdTool.parameters.shape, + getTestById, +); + server.tool( GetTestEntitiesTool.name, GetTestEntitiesTool.description, diff --git a/src/operations/tests.ts b/src/operations/tests.ts index 064c47d..cf95a6a 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -3,6 +3,10 @@ import { z } from "zod"; import { Tool } from "../types.js"; import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "../global-descriptions.js"; export async function getTests( args: z.infer, @@ -12,6 +16,9 @@ export async function getTests( if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } if (args.statusFilter !== undefined) { url.searchParams.append("statusFilter", args.statusFilter); } @@ -79,15 +86,41 @@ export async function getTestEntities( }; } -const TOOL_DESCRIPTION = `Retrieve Vanta's automated security and compliance tests. Vanta runs 1,200+ automated tests continuously to monitor compliance across your infrastructure. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. Tests that are NOT_APPLICABLE to your resources are included by default - use statusFilter=NEEDS_ATTENTION to retrieve only actionable failing tests.`; +export async function getTestById( + args: z.infer, +): Promise { + const url = new URL(`/v1/tests/${args.testId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Url: ${url.toString()}, Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +const TOOL_DESCRIPTION = `Retrieve Vanta's automated security and compliance tests. Vanta runs 1,200+ automated tests +continuously to monitor compliance across your infrastructure. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), +cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results +showing which security controls are passing or failing across your infrastructure. Tests that are NOT_APPLICABLE +to your resources are included by default - use statusFilter=NEEDS_ATTENTION to retrieve only actionable failing tests.`; const TEST_STATUS_FILTER_DESCRIPTION = `Filter tests by their status. Helpful for retrieving only relevant or actionable results. Possible values: OK, DEACTIVATED, NEEDS_ATTENTION, IN_PROGRESS, INVALID, NOT_APPLICABLE.`; -const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of tests returned in a single response. -Allowed values: 1–100. Default is 10.`; - const INTEGRATION_FILTER_DESCRIPTION = `Filter by integration. Non-exhaustive examples of possible values include aws, azure, gcp, snyk.`; const FRAMEWORK_FILTER_DESCRIPTION = `Filter by framework. Non-exhaustive examples: soc2, ccpa, fedramp`; @@ -96,6 +129,7 @@ const CONTROL_FILTER_DESCRIPTION = `Filter by control. Generally will only be kn export const GetTestsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), statusFilter: z.string().describe(TEST_STATUS_FILTER_DESCRIPTION).optional(), integrationFilter: z .string() @@ -113,16 +147,8 @@ export const GetTestsTool: Tool = { const GetTestEntitiesInput = z.object({ testId: z.string().describe("Lowercase with hyphens"), - pageSize: z - .number() - .describe( - "Controls the maximum number of tests returned in a single response. Allowed values: 1–100. Default is 10.", - ) - .optional(), - pageCursor: z - .string() - .describe("Used for pagination. Leave blank to start from the first page.") - .optional(), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), entityStatus: z .string() .describe("Filter by entity status. Possible values: FAILING, DEACTIVATED.") @@ -131,6 +157,20 @@ const GetTestEntitiesInput = z.object({ export const GetTestEntitiesTool: Tool = { name: "get_test_entities", - description: `Get the specific failing resources (entities) for a known test ID. Use this when you already know the test name/ID and need to see which specific infrastructure resources are failing that test. For example, if you know "aws-security-groups-open-to-world" test is failing, this returns the actual security group IDs that are failing. Requires a specific testId parameter. Do NOT use this for general test discovery - use get_tests for that.`, + description: `Get the specific failing resources (entities) for a known test ID. Use this when you already + know the test name/ID and need to see which specific infrastructure resources are failing that test. For + example, if you know "aws-security-groups-open-to-world" test is failing, this returns the actual security + group IDs that are failing. Requires a specific testId parameter. Do NOT use this for general test discovery - use get_tests for that.`, parameters: GetTestEntitiesInput, }; + +const GetTestByIdInput = z.object({ + testId: z.string().describe("Lowercase with hyphens"), +}); + +export const GetTestByIdTool: Tool = { + name: "get_test_by_id", + description: `Get the details of a single specific test when its ID is known. The ID of a test can be + found in the response from get_tests or from the URL of the test in your browser after /tests/.`, + parameters: GetTestByIdInput, +}; From 6c1616e082ba6b0e259c630cc77efe343779396b Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 13:53:23 -0400 Subject: [PATCH 03/24] Add additional GET endpoints for Controls --- README.md | 3 + src/eval/README.md | 10 ++- src/eval/eval.ts | 45 +++++++++++ src/index.ts | 27 +++++++ src/operations/controls.ts | 153 ++++++++++++++++++++++++++++++++++--- 5 files changed, 223 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 9ba9960..aaa42fb 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,9 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_framework_controls` | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | | `get_controls` | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | | `get_control_tests` | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | +| `get_library_controls` | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from get_controls which lists controls already in your account - this shows available controls you can implement. | +| `get_control_documents` | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | +| `get_control_by_id` | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from get_controls or get_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | | `get_risks` | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 52cd00b..1f6af8c 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,19 +40,21 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 11 test cases covering: +The evaluation includes 13 test cases covering: ### ✅ **Tool Selection Tests** - **AWS Security Review**: `get_tests` with AWS and NEEDS_ATTENTION filters - **SOC2 Compliance**: `get_tests` with SOC2 framework filter - **Entity Details**: `get_test_entities` for specific failing resources -- **Maintenance Deactivation**: `deactivate_test_entity` for suppressing alerts - **Framework Listing**: `get_frameworks` for available frameworks - **Control Requirements**: `get_framework_controls` for specific framework details - **Status Percentage**: `get_frameworks` for completion percentages - **Control Listing**: `get_controls` for all security controls - **Control Tests**: `get_control_tests` for tests validating specific controls +- **Library Controls**: `get_library_controls` for available Vanta library controls +- **Control Documents**: `get_control_documents` for documents associated with controls +- **Control Details**: `get_control_by_id` for specific control information ### ❌ **Negative Tests** @@ -77,8 +79,8 @@ The evaluation includes 11 test cases covering: 📊 Final Results ================ -✅ Passed: 11/11 tests -❌ Failed: 0/11 tests +✅ Passed: 13/13 tests +❌ Failed: 0/13 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 43b08ce..5b466c1 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -8,6 +8,9 @@ import { import { GetControlsTool, GetControlTestsTool, + GetLibraryControlsTool, + GetControlDocumentsTool, + GetControlByIdTool, } from "../operations/controls.js"; import { GetRisksTool } from "../operations/risks.js"; @@ -61,6 +64,30 @@ const tools = [ parameters: zodToJsonSchema(GetControlTestsTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetLibraryControlsTool.name, + description: GetLibraryControlsTool.description, + parameters: zodToJsonSchema(GetLibraryControlsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetControlDocumentsTool.name, + description: GetControlDocumentsTool.description, + parameters: zodToJsonSchema(GetControlDocumentsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetControlByIdTool.name, + description: GetControlByIdTool.description, + parameters: zodToJsonSchema(GetControlByIdTool.parameters), + }, + }, { type: "function" as const, function: { @@ -142,6 +169,24 @@ const testCases: TestCase[] = [ expectedParams: { controlId: "access-control-1" }, description: "Should call get_control_tests for specific control", }, + { + prompt: "What controls are available in the Vanta library that I can add?", + expectedTool: "get_library_controls", + expectedParams: {}, + description: "Should call get_library_controls to list available library controls", + }, + { + prompt: "Show me the documents for control ID access-control-1", + expectedTool: "get_control_documents", + expectedParams: { controlId: "access-control-1" }, + description: "Should call get_control_documents for specific control", + }, + { + prompt: "Get details for control ID data-protection-2", + expectedTool: "get_control_by_id", + expectedParams: { controlId: "data-protection-2" }, + description: "Should call get_control_by_id for specific control details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index 118f980..1a98fbf 100644 --- a/src/index.ts +++ b/src/index.ts @@ -19,8 +19,14 @@ import { import { GetControlsTool, GetControlTestsTool, + GetLibraryControlsTool, + GetControlDocumentsTool, + GetControlByIdTool, getControls, getControlTests, + getLibraryControls, + getControlDocuments, + getControlById, } from "./operations/controls.js"; import { getRisks, GetRisksTool } from "./operations/risks.js"; import { initializeToken } from "./auth.js"; @@ -81,6 +87,27 @@ server.tool( getControlTests, ); +server.tool( + GetLibraryControlsTool.name, + GetLibraryControlsTool.description, + GetLibraryControlsTool.parameters.shape, + getLibraryControls, +); + +server.tool( + GetControlDocumentsTool.name, + GetControlDocumentsTool.description, + GetControlDocumentsTool.parameters.shape, + getControlDocuments, +); + +server.tool( + GetControlByIdTool.name, + GetControlByIdTool.description, + GetControlByIdTool.parameters.shape, + getControlById, +); + server.tool( GetRisksTool.name, GetRisksTool.description, diff --git a/src/operations/controls.ts b/src/operations/controls.ts index ec287a8..e6577af 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -3,13 +3,14 @@ import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "../global-descriptions.js"; const GetControlsInput = z.object({ - pageSize: z - .number() - .describe("Number of controls to return (1-100, default 10)") - .optional(), - pageCursor: z.string().describe("Pagination cursor for next page").optional(), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), frameworkMatchesAny: z .array(z.string()) .describe( @@ -31,20 +32,61 @@ const GetControlTestsInput = z.object({ .describe( "Control ID to get tests for, e.g. 'access-control-1' or 'data-protection-2'", ), - pageSize: z - .number() - .describe("Number of tests to return (1-100, default 10)") - .optional(), - pageCursor: z.string().describe("Pagination cursor for next page").optional(), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); export const GetControlTestsTool: Tool = { name: "get_control_tests", description: - "Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests.", + "List a control's tests. Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests.", parameters: GetControlTestsInput, }; +const GetLibraryControlsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetLibraryControlsTool: Tool = { + name: "get_library_controls", + description: + "List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from get_controls which lists controls already in your account - this shows available controls you can implement.", + parameters: GetLibraryControlsInput, +}; + +const GetControlDocumentsInput = z.object({ + controlId: z + .string() + .describe( + "Control ID to get documents for, e.g. 'access-control-1' or 'data-protection-2'", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetControlDocumentsTool: Tool = { + name: "get_control_documents", + description: + "List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence.", + parameters: GetControlDocumentsInput, +}; + +const GetControlByIdInput = z.object({ + controlId: z + .string() + .describe( + "Control ID to retrieve, e.g. 'access-control-1' or 'data-protection-2'", + ), +}); + +export const GetControlByIdTool: Tool = { + name: "get_control_by_id", + description: + "Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from get_controls or get_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status.", + parameters: GetControlByIdInput, +}; + export async function getControls( args: z.infer, ): Promise { @@ -113,3 +155,92 @@ export async function getControlTests( ], }; } + +export async function getLibraryControls( + args: z.infer, +): Promise { + const url = new URL("/v1/controls/controls-library", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getControlDocuments( + args: z.infer, +): Promise { + const url = new URL(`/v1/controls/${args.controlId}/documents`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getControlById( + args: z.infer, +): Promise { + const url = new URL(`/v1/controls/${args.controlId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 5d39b57e3c857b7274c2cb2bba3e73011a9bc75a Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 15:40:29 -0400 Subject: [PATCH 04/24] Expand coverage for Frameworks and Tests endpoints --- README.md | 2 ++ src/eval/README.md | 8 ++++-- src/eval/eval.ts | 31 ++++++++++++++++++++- src/index.ts | 18 +++++++++++- src/operations/frameworks.ts | 49 ++++++++++++++++++++++++++++++--- src/operations/risks.ts | 53 +++++++++++++++++++++++++++++------- 6 files changed, 142 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index aaa42fb..26d0640 100644 --- a/README.md +++ b/README.md @@ -46,12 +46,14 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_test_by_id` | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `get_tests` response or from the address bar of your browser after /tests/. | | `get_frameworks` | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | | `get_framework_controls` | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | +| `get_framework_by_id` | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from get_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | | `get_controls` | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | | `get_control_tests` | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | | `get_library_controls` | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from get_controls which lists controls already in your account - this shows available controls you can implement. | | `get_control_documents` | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | | `get_control_by_id` | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from get_controls or get_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | | `get_risks` | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | +| `get_risk_by_id` | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from get_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 1f6af8c..b7d21e2 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 13 test cases covering: +The evaluation includes 15 test cases covering: ### ✅ **Tool Selection Tests** @@ -55,6 +55,8 @@ The evaluation includes 13 test cases covering: - **Library Controls**: `get_library_controls` for available Vanta library controls - **Control Documents**: `get_control_documents` for documents associated with controls - **Control Details**: `get_control_by_id` for specific control information +- **Framework Details**: `get_framework_by_id` for specific framework information +- **Risk Details**: `get_risk_by_id` for specific risk scenario information ### ❌ **Negative Tests** @@ -79,8 +81,8 @@ The evaluation includes 13 test cases covering: 📊 Final Results ================ -✅ Passed: 13/13 tests -❌ Failed: 0/13 tests +✅ Passed: 15/15 tests +❌ Failed: 0/15 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 5b466c1..3140c2f 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -4,6 +4,7 @@ import { GetTestsTool, GetTestEntitiesTool } from "../operations/tests.js"; import { GetFrameworksTool, GetFrameworkControlsTool, + GetFrameworkByIdTool, } from "../operations/frameworks.js"; import { GetControlsTool, @@ -12,7 +13,7 @@ import { GetControlDocumentsTool, GetControlByIdTool, } from "../operations/controls.js"; -import { GetRisksTool } from "../operations/risks.js"; +import { GetRisksTool, GetRiskByIdTool } from "../operations/risks.js"; // Format all tools for OpenAI const tools = [ @@ -96,6 +97,22 @@ const tools = [ parameters: zodToJsonSchema(GetRisksTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetRiskByIdTool.name, + description: GetRiskByIdTool.description, + parameters: zodToJsonSchema(GetRiskByIdTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetFrameworkByIdTool.name, + description: GetFrameworkByIdTool.description, + parameters: zodToJsonSchema(GetFrameworkByIdTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -187,6 +204,18 @@ const testCases: TestCase[] = [ expectedParams: { controlId: "data-protection-2" }, description: "Should call get_control_by_id for specific control details", }, + { + prompt: "Show me details for framework ID soc2", + expectedTool: "get_framework_by_id", + expectedParams: { frameworkId: "soc2" }, + description: "Should call get_framework_by_id for specific framework details", + }, + { + prompt: "Get details for risk scenario ID risk-scenario-123", + expectedTool: "get_risk_by_id", + expectedParams: { riskId: "risk-scenario-123" }, + description: "Should call get_risk_by_id for specific risk scenario details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index 1a98fbf..31b924c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -13,8 +13,10 @@ import { import { GetFrameworkControlsTool, GetFrameworksTool, + GetFrameworkByIdTool, getFrameworkControls, getFrameworks, + getFrameworkById, } from "./operations/frameworks.js"; import { GetControlsTool, @@ -28,7 +30,7 @@ import { getControlDocuments, getControlById, } from "./operations/controls.js"; -import { getRisks, GetRisksTool } from "./operations/risks.js"; +import { getRisks, GetRisksTool, getRiskById, GetRiskByIdTool } from "./operations/risks.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -73,6 +75,13 @@ server.tool( getFrameworkControls, ); +server.tool( + GetFrameworkByIdTool.name, + GetFrameworkByIdTool.description, + GetFrameworkByIdTool.parameters.shape, + getFrameworkById, +); + server.tool( GetControlsTool.name, GetControlsTool.description, @@ -115,6 +124,13 @@ server.tool( getRisks, ); +server.tool( + GetRiskByIdTool.name, + GetRiskByIdTool.description, + GetRiskByIdTool.parameters.shape, + getRiskById, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index 093af61..7b5cf7b 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -3,10 +3,14 @@ import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "../global-descriptions.js"; const GetFrameworksInput = z.object({ - pageSize: z.number().optional(), - pageCursor: z.string().optional(), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); export const GetFrameworksTool: Tool = { @@ -18,8 +22,8 @@ export const GetFrameworksTool: Tool = { const GetFrameworkControlsInput = z.object({ frameworkId: z.string(), - pageSize: z.number().optional(), - pageCursor: z.string().optional(), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); export const GetFrameworkControlsTool: Tool = @@ -30,6 +34,21 @@ export const GetFrameworkControlsTool: Tool = parameters: GetFrameworkControlsInput, }; +const GetFrameworkByIdInput = z.object({ + frameworkId: z + .string() + .describe( + "Framework ID to retrieve, e.g. 'soc2', 'iso27001', 'hipaa', 'gdpr'", + ), +}); + +export const GetFrameworkByIdTool: Tool = { + name: "get_framework_by_id", + description: + "Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from get_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state.", + parameters: GetFrameworkByIdInput, +}; + export async function getFrameworkControls( args: z.infer, ): Promise { @@ -87,3 +106,25 @@ export async function getFrameworks( ], }; } + +export async function getFrameworkById( + args: z.infer, +): Promise { + const url = new URL(`/v1/frameworks/${args.frameworkId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { type: "text" as const, text: `Error: ${response.statusText}` }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} diff --git a/src/operations/risks.ts b/src/operations/risks.ts index 7266dac..cabca71 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -3,18 +3,14 @@ import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "../global-descriptions.js"; const GetRisksInput = z.object({ - pageSize: z - .number() - .optional() - .describe( - "Controls the maximum number of risks returned in a single response. Allowed values: 1–100. Default is 10.", - ), - pageCursor: z - .string() - .optional() - .describe("Used for pagination. Leave blank to start from the first page."), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), categoryMatchesAny: z .string() .optional() @@ -29,6 +25,21 @@ export const GetRisksTool: Tool = { parameters: GetRisksInput, }; +const GetRiskByIdInput = z.object({ + riskId: z + .string() + .describe( + "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier", + ), +}); + +export const GetRiskByIdTool: Tool = { + name: "get_risk_by_id", + description: + "Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from get_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more.", + parameters: GetRiskByIdInput, +}; + export async function getRisks( args: z.infer, ): Promise { @@ -59,3 +70,25 @@ export async function getRisks( ], }; } + +export async function getRiskById( + args: z.infer, +): Promise { + const url = new URL(`/v1/risk-scenarios/${args.riskId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { type: "text" as const, text: `Error: ${response.statusText}` }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 583477ddc615c7796ca78d4ab4e85bcc78ada1e4 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 15:58:09 -0400 Subject: [PATCH 05/24] Add support for Integrations and Vendors --- README.md | 36 ++++++++++++++ src/eval/README.md | 10 ++-- src/eval/eval.ts | 64 ++++++++++++++++++++++++ src/index.ts | 121 +++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 228 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 26d0640..d8a674f 100644 --- a/README.md +++ b/README.md @@ -32,6 +32,29 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. - Filterable by risk category (Access Control, Cryptography, Privacy, and many others). +### Integration Management + +- List all connected integrations in your Vanta account (AWS, Azure, GCP, Snyk, etc.) +- Get detailed information about specific integrations and their configurations +- View integration resource kinds and connection status +- Monitor which integrations are actively connected to your instance +- List resource types (kinds) that integrations can monitor (S3Bucket, CloudwatchLogGroup, etc.) +- Get detailed information about specific resource types and their properties +- List all infrastructure resources discovered by integrations +- Access detailed resource information including metadata, compliance status, and configuration + +### Vendor Management + +- List all vendors in your Vanta account for vendor risk management +- Get detailed vendor information including contact details and website URLs +- Access vendor risk assessment status and compliance information +- Manage vendor relationships and due diligence tracking +- View all documents associated with vendors for compliance purposes +- Access security findings and risk assessment results for vendors +- Review history of security assessments and due diligence activities +- Get detailed information about specific vendor security reviews +- Access supporting documentation and reports for security assessments + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -54,6 +77,19 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_control_by_id` | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from get_controls or get_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | | `get_risks` | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | | `get_risk_by_id` | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from get_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | +| `get_integrations` | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | +| `get_integration_by_id` | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from get_integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | +| `get_integration_resource_kinds` | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | +| `get_integration_resource_kind_details` | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | +| `get_integration_resources` | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | +| `get_integration_resource_by_id` | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | +| `get_vendors` | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | +| `get_vendor_by_id` | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from get_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | +| `get_vendor_documents` | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | +| `get_vendor_findings` | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | +| `get_vendor_security_reviews` | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | +| `get_vendor_security_review_by_id` | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | +| `get_vendor_security_review_documents` | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index b7d21e2..4cff73d 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 15 test cases covering: +The evaluation includes 19 test cases covering: ### ✅ **Tool Selection Tests** @@ -57,6 +57,10 @@ The evaluation includes 15 test cases covering: - **Control Details**: `get_control_by_id` for specific control information - **Framework Details**: `get_framework_by_id` for specific framework information - **Risk Details**: `get_risk_by_id` for specific risk scenario information +- **Integration Listing**: `get_integrations` for connected integrations +- **Integration Details**: `get_integration_by_id` for specific integration information +- **Vendor Listing**: `get_vendors` for all vendors +- **Vendor Details**: `get_vendor_by_id` for specific vendor information ### ❌ **Negative Tests** @@ -81,8 +85,8 @@ The evaluation includes 15 test cases covering: 📊 Final Results ================ -✅ Passed: 15/15 tests -❌ Failed: 0/15 tests +✅ Passed: 19/19 tests +❌ Failed: 0/19 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 3140c2f..2012ef2 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -14,6 +14,14 @@ import { GetControlByIdTool, } from "../operations/controls.js"; import { GetRisksTool, GetRiskByIdTool } from "../operations/risks.js"; +import { + GetIntegrationsTool, + GetIntegrationByIdTool, +} from "../operations/integrations.js"; +import { + GetVendorsTool, + GetVendorByIdTool, +} from "../operations/vendors.js"; // Format all tools for OpenAI const tools = [ @@ -113,6 +121,38 @@ const tools = [ parameters: zodToJsonSchema(GetFrameworkByIdTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetIntegrationsTool.name, + description: GetIntegrationsTool.description, + parameters: zodToJsonSchema(GetIntegrationsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetIntegrationByIdTool.name, + description: GetIntegrationByIdTool.description, + parameters: zodToJsonSchema(GetIntegrationByIdTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVendorsTool.name, + description: GetVendorsTool.description, + parameters: zodToJsonSchema(GetVendorsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVendorByIdTool.name, + description: GetVendorByIdTool.description, + parameters: zodToJsonSchema(GetVendorByIdTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -216,6 +256,30 @@ const testCases: TestCase[] = [ expectedParams: { riskId: "risk-scenario-123" }, description: "Should call get_risk_by_id for specific risk scenario details", }, + { + prompt: "What integrations are connected to my Vanta account?", + expectedTool: "get_integrations", + expectedParams: {}, + description: "Should call get_integrations to list all connected integrations", + }, + { + prompt: "Show me details for integration ID aws", + expectedTool: "get_integration_by_id", + expectedParams: { integrationId: "aws" }, + description: "Should call get_integration_by_id for specific integration details", + }, + { + prompt: "List all vendors in my Vanta account", + expectedTool: "get_vendors", + expectedParams: {}, + description: "Should call get_vendors to list all vendors", + }, + { + prompt: "Get details for vendor ID vendor-123", + expectedTool: "get_vendor_by_id", + expectedParams: { vendorId: "vendor-123" }, + description: "Should call get_vendor_by_id for specific vendor details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index 31b924c..3aa414e 100644 --- a/src/index.ts +++ b/src/index.ts @@ -31,6 +31,36 @@ import { getControlById, } from "./operations/controls.js"; import { getRisks, GetRisksTool, getRiskById, GetRiskByIdTool } from "./operations/risks.js"; +import { + getIntegrations, + GetIntegrationsTool, + getIntegrationById, + GetIntegrationByIdTool, + getIntegrationResourceKinds, + GetIntegrationResourceKindsTool, + getIntegrationResourceKindDetails, + GetIntegrationResourceKindDetailsTool, + getIntegrationResources, + GetIntegrationResourcesTool, + getIntegrationResourceById, + GetIntegrationResourceByIdTool, +} from "./operations/integrations.js"; +import { + getVendors, + GetVendorsTool, + getVendorById, + GetVendorByIdTool, + getVendorDocuments, + GetVendorDocumentsTool, + getVendorFindings, + GetVendorFindingsTool, + getVendorSecurityReviews, + GetVendorSecurityReviewsTool, + getVendorSecurityReviewById, + GetVendorSecurityReviewByIdTool, + getVendorSecurityReviewDocuments, + GetVendorSecurityReviewDocumentsTool, +} from "./operations/vendors.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -131,6 +161,97 @@ server.tool( getRiskById, ); +server.tool( + GetIntegrationsTool.name, + GetIntegrationsTool.description, + GetIntegrationsTool.parameters.shape, + getIntegrations, +); + +server.tool( + GetIntegrationByIdTool.name, + GetIntegrationByIdTool.description, + GetIntegrationByIdTool.parameters.shape, + getIntegrationById, +); + +server.tool( + GetIntegrationResourceKindsTool.name, + GetIntegrationResourceKindsTool.description, + GetIntegrationResourceKindsTool.parameters.shape, + getIntegrationResourceKinds, +); + +server.tool( + GetIntegrationResourceKindDetailsTool.name, + GetIntegrationResourceKindDetailsTool.description, + GetIntegrationResourceKindDetailsTool.parameters.shape, + getIntegrationResourceKindDetails, +); + +server.tool( + GetIntegrationResourcesTool.name, + GetIntegrationResourcesTool.description, + GetIntegrationResourcesTool.parameters.shape, + getIntegrationResources, +); + +server.tool( + GetIntegrationResourceByIdTool.name, + GetIntegrationResourceByIdTool.description, + GetIntegrationResourceByIdTool.parameters.shape, + getIntegrationResourceById, +); + +server.tool( + GetVendorsTool.name, + GetVendorsTool.description, + GetVendorsTool.parameters.shape, + getVendors, +); + +server.tool( + GetVendorByIdTool.name, + GetVendorByIdTool.description, + GetVendorByIdTool.parameters.shape, + getVendorById, +); + +server.tool( + GetVendorDocumentsTool.name, + GetVendorDocumentsTool.description, + GetVendorDocumentsTool.parameters.shape, + getVendorDocuments, +); + +server.tool( + GetVendorFindingsTool.name, + GetVendorFindingsTool.description, + GetVendorFindingsTool.parameters.shape, + getVendorFindings, +); + +server.tool( + GetVendorSecurityReviewsTool.name, + GetVendorSecurityReviewsTool.description, + GetVendorSecurityReviewsTool.parameters.shape, + getVendorSecurityReviews, +); + +server.tool( + GetVendorSecurityReviewByIdTool.name, + GetVendorSecurityReviewByIdTool.description, + GetVendorSecurityReviewByIdTool.parameters.shape, + getVendorSecurityReviewById, +); + +server.tool( + GetVendorSecurityReviewDocumentsTool.name, + GetVendorSecurityReviewDocumentsTool.description, + GetVendorSecurityReviewDocumentsTool.parameters.shape, + getVendorSecurityReviewDocuments, +); + async function main() { try { await initializeToken(); From 68054a8b500069eafcc7ed594d2b50f07cf21b7c Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 16:00:27 -0400 Subject: [PATCH 06/24] Add integrations and vendors operations files I neglected to commit --- src/operations/integrations.ts | 281 +++++++++++++++++++++++++++ src/operations/vendors.ts | 339 +++++++++++++++++++++++++++++++++ 2 files changed, 620 insertions(+) create mode 100644 src/operations/integrations.ts create mode 100644 src/operations/vendors.ts diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts new file mode 100644 index 0000000..b112dfc --- /dev/null +++ b/src/operations/integrations.ts @@ -0,0 +1,281 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "../global-descriptions.js"; + +const GetIntegrationsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetIntegrationsTool: Tool = { + name: "get_integrations", + description: + "List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance.", + parameters: GetIntegrationsInput, +}; + +const GetIntegrationByIdInput = z.object({ + integrationId: z + .string() + .describe( + "Integration ID to retrieve, e.g. 'aws', 'azure', 'gcp', or specific integration identifier", + ), +}); + +export const GetIntegrationByIdTool: Tool = { + name: "get_integration_by_id", + description: + "Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from get_integrations response. Returns complete integration details including configuration, resource kinds, and connection status.", + parameters: GetIntegrationByIdInput, +}; + +const GetIntegrationResourceKindsInput = z.object({ + integrationId: z + .string() + .describe( + "Integration ID to get resource kinds for, e.g. 'aws', 'azure', 'gcp'", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetIntegrationResourceKindsTool: Tool = { + name: "get_integration_resource_kinds", + description: + "List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor.", + parameters: GetIntegrationResourceKindsInput, +}; + +const GetIntegrationResourceKindDetailsInput = z.object({ + integrationId: z + .string() + .describe( + "Integration ID to get resource kind details for, e.g. 'aws', 'azure', 'gcp'", + ), + resourceKind: z + .string() + .describe( + "Resource kind to get details for, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + ), +}); + +export const GetIntegrationResourceKindDetailsTool: Tool = { + name: "get_integration_resource_kind_details", + description: + "Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type.", + parameters: GetIntegrationResourceKindDetailsInput, +}; + +const GetIntegrationResourcesInput = z.object({ + integrationId: z + .string() + .describe( + "Integration ID to get resources for, e.g. 'aws', 'azure', 'gcp'", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetIntegrationResourcesTool: Tool = { + name: "get_integration_resources", + description: + "List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration.", + parameters: GetIntegrationResourcesInput, +}; + +const GetIntegrationResourceByIdInput = z.object({ + integrationId: z + .string() + .describe( + "Integration ID that owns the resource, e.g. 'aws', 'azure', 'gcp'", + ), + resourceId: z + .string() + .describe( + "Resource ID to get details for, e.g. 'i-1234567890abcdef0', 'bucket-name'", + ), +}); + +export const GetIntegrationResourceByIdTool: Tool = { + name: "get_integration_resource_by_id", + description: + "Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration.", + parameters: GetIntegrationResourceByIdInput, +}; + +export async function getIntegrations( + args: z.infer, +): Promise { + const url = new URL("/v1/integrations", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getIntegrationById( + args: z.infer, +): Promise { + const url = new URL(`/v1/integrations/${args.integrationId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getIntegrationResourceKinds( + args: z.infer, +): Promise { + const url = new URL(`/v1/integrations/${args.integrationId}/resource-kinds`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getIntegrationResourceKindDetails( + args: z.infer, +): Promise { + const url = new URL(`/v1/integrations/${args.integrationId}/resource-kinds/${args.resourceKind}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getIntegrationResources( + args: z.infer, +): Promise { + const url = new URL(`/v1/integrations/${args.integrationId}/resources`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getIntegrationResourceById( + args: z.infer, +): Promise { + const url = new URL(`/v1/integrations/${args.integrationId}/resources/${args.resourceId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts new file mode 100644 index 0000000..247a5b3 --- /dev/null +++ b/src/operations/vendors.ts @@ -0,0 +1,339 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "../global-descriptions.js"; + +const GetVendorsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVendorsTool: Tool = { + name: "get_vendors", + description: + "List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors.", + parameters: GetVendorsInput, +}; + +const GetVendorByIdInput = z.object({ + vendorId: z + .string() + .describe( + "Vendor ID to retrieve, e.g. 'vendor-123' or specific vendor identifier", + ), +}); + +export const GetVendorByIdTool: Tool = { + name: "get_vendor_by_id", + description: + "Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from get_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status.", + parameters: GetVendorByIdInput, +}; + +const GetVendorDocumentsInput = z.object({ + vendorId: z + .string() + .describe( + "Vendor ID to get documents for, e.g. 'vendor-123' or specific vendor identifier", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVendorDocumentsTool: Tool = { + name: "get_vendor_documents", + description: + "List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence.", + parameters: GetVendorDocumentsInput, +}; + +const GetVendorFindingsInput = z.object({ + vendorId: z + .string() + .describe( + "Vendor ID to get findings for, e.g. 'vendor-123' or specific vendor identifier", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVendorFindingsTool: Tool = { + name: "get_vendor_findings", + description: + "List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor.", + parameters: GetVendorFindingsInput, +}; + +const GetVendorSecurityReviewsInput = z.object({ + vendorId: z + .string() + .describe( + "Vendor ID to get security reviews for, e.g. 'vendor-123' or specific vendor identifier", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVendorSecurityReviewsTool: Tool = { + name: "get_vendor_security_reviews", + description: + "Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities.", + parameters: GetVendorSecurityReviewsInput, +}; + +const GetVendorSecurityReviewByIdInput = z.object({ + vendorId: z + .string() + .describe( + "Vendor ID that owns the security review, e.g. 'vendor-123'", + ), + securityReviewId: z + .string() + .describe( + "Security review ID to get details for, e.g. 'security-review-456'", + ), +}); + +export const GetVendorSecurityReviewByIdTool: Tool = { + name: "get_vendor_security_review_by_id", + description: + "Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations.", + parameters: GetVendorSecurityReviewByIdInput, +}; + +const GetVendorSecurityReviewDocumentsInput = z.object({ + vendorId: z + .string() + .describe( + "Vendor ID that owns the security review, e.g. 'vendor-123'", + ), + securityReviewId: z + .string() + .describe( + "Security review ID to get documents for, e.g. 'security-review-456'", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVendorSecurityReviewDocumentsTool: Tool = { + name: "get_vendor_security_review_documents", + description: + "Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment.", + parameters: GetVendorSecurityReviewDocumentsInput, +}; + +export async function getVendors( + args: z.infer, +): Promise { + const url = new URL("/v1/vendors", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVendorById( + args: z.infer, +): Promise { + const url = new URL(`/v1/vendors/${args.vendorId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVendorDocuments( + args: z.infer, +): Promise { + const url = new URL(`/v1/vendors/${args.vendorId}/documents`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVendorFindings( + args: z.infer, +): Promise { + const url = new URL(`/v1/vendors/${args.vendorId}/findings`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVendorSecurityReviews( + args: z.infer, +): Promise { + const url = new URL(`/v1/vendors/${args.vendorId}/security-reviews`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVendorSecurityReviewById( + args: z.infer, +): Promise { + const url = new URL(`/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVendorSecurityReviewDocuments( + args: z.infer, +): Promise { + const url = new URL(`/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}/documents`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From b932911b83c4e466c92708ca97938f51ca69364f Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 16:43:51 -0400 Subject: [PATCH 07/24] Add support for Documents endpoints and relocate global-descriptions --- README.md | 15 + src/eval/README.md | 12 +- src/eval/eval.ts | 92 ++++++ src/index.ts | 56 ++++ src/operations/controls.ts | 2 +- src/operations/documents.ts | 309 ++++++++++++++++++++ src/operations/frameworks.ts | 2 +- src/{ => operations}/global-descriptions.ts | 5 +- src/operations/integrations.ts | 2 +- src/operations/risks.ts | 2 +- src/operations/tests.ts | 2 +- src/operations/vendors.ts | 2 +- 12 files changed, 491 insertions(+), 10 deletions(-) create mode 100644 src/operations/documents.ts rename src/{ => operations}/global-descriptions.ts (69%) diff --git a/README.md b/README.md index d8a674f..ddf0925 100644 --- a/README.md +++ b/README.md @@ -55,6 +55,15 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Get detailed information about specific vendor security reviews - Access supporting documentation and reports for security assessments +### Document Management + +- List all documents in your Vanta account for compliance and evidence management +- Get detailed information about specific documents including metadata and compliance mappings +- View security controls that are mapped to or associated with documents as evidence +- Access external links and references associated with documents +- List all files and uploads attached to documents for compliance documentation +- Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -90,6 +99,12 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_vendor_security_reviews` | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | | `get_vendor_security_review_by_id` | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | | `get_vendor_security_review_documents` | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | +| `get_documents` | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | +| `get_document_by_id` | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from get_documents response. Returns complete document details including name, type, metadata, and compliance mappings. | +| `get_document_controls` | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | +| `get_document_links` | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | +| `get_document_uploads` | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | +| `download_document_file` | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 4cff73d..1d8aa94 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 19 test cases covering: +The evaluation includes 25 test cases covering: ### ✅ **Tool Selection Tests** @@ -61,6 +61,12 @@ The evaluation includes 19 test cases covering: - **Integration Details**: `get_integration_by_id` for specific integration information - **Vendor Listing**: `get_vendors` for all vendors - **Vendor Details**: `get_vendor_by_id` for specific vendor information +- **Document Listing**: `get_documents` for all compliance documents +- **Document Details**: `get_document_by_id` for specific document information +- **Document Controls**: `get_document_controls` for controls associated with documents +- **Document Links**: `get_document_links` for external references in documents +- **Document Uploads**: `get_document_uploads` for file uploads attached to documents +- **Document Downloads**: `download_document_file` for intelligently downloading files (text content for readable files, metadata for binary files) ### ❌ **Negative Tests** @@ -85,8 +91,8 @@ The evaluation includes 19 test cases covering: 📊 Final Results ================ -✅ Passed: 19/19 tests -❌ Failed: 0/19 tests +✅ Passed: 25/25 tests +❌ Failed: 0/25 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 2012ef2..4d7d541 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -22,6 +22,14 @@ import { GetVendorsTool, GetVendorByIdTool, } from "../operations/vendors.js"; +import { + GetDocumentsTool, + GetDocumentByIdTool, + GetDocumentControlsTool, + GetDocumentLinksTool, + GetDocumentUploadsTool, + DownloadDocumentFileTool, +} from "../operations/documents.js"; // Format all tools for OpenAI const tools = [ @@ -153,6 +161,54 @@ const tools = [ parameters: zodToJsonSchema(GetVendorByIdTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetDocumentsTool.name, + description: GetDocumentsTool.description, + parameters: zodToJsonSchema(GetDocumentsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetDocumentByIdTool.name, + description: GetDocumentByIdTool.description, + parameters: zodToJsonSchema(GetDocumentByIdTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetDocumentControlsTool.name, + description: GetDocumentControlsTool.description, + parameters: zodToJsonSchema(GetDocumentControlsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetDocumentLinksTool.name, + description: GetDocumentLinksTool.description, + parameters: zodToJsonSchema(GetDocumentLinksTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetDocumentUploadsTool.name, + description: GetDocumentUploadsTool.description, + parameters: zodToJsonSchema(GetDocumentUploadsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: DownloadDocumentFileTool.name, + description: DownloadDocumentFileTool.description, + parameters: zodToJsonSchema(DownloadDocumentFileTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -280,6 +336,42 @@ const testCases: TestCase[] = [ expectedParams: { vendorId: "vendor-123" }, description: "Should call get_vendor_by_id for specific vendor details", }, + { + prompt: "Show me all the documents we have uploaded to Vanta for compliance purposes.", + expectedTool: "get_documents", + expectedParams: {}, + description: "Should call get_documents to list all compliance documents", + }, + { + prompt: "I need to see the details of document DOC-12345 including its metadata and compliance mappings.", + expectedTool: "get_document_by_id", + expectedParams: { documentId: "DOC-12345" }, + description: "Should call get_document_by_id for specific document details", + }, + { + prompt: "Which security controls are mapped to document DOC-789?", + expectedTool: "get_document_controls", + expectedParams: { documentId: "DOC-789" }, + description: "Should call get_document_controls to find controls associated with document", + }, + { + prompt: "What external links and references are attached to document POLICY-456?", + expectedTool: "get_document_links", + expectedParams: { documentId: "POLICY-456" }, + description: "Should call get_document_links to get external references for document", + }, + { + prompt: "List all the files uploaded to document SEC-123.", + expectedTool: "get_document_uploads", + expectedParams: { documentId: "SEC-123" }, + description: "Should call get_document_uploads to list file uploads for document", + }, + { + prompt: "I need to download the file with uploaded file ID FILE-456 from document DOC-789.", + expectedTool: "download_document_file", + expectedParams: { documentId: "DOC-789", uploadedFileId: "FILE-456" }, + description: "Should call download_document_file to download specific file from document", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index 3aa414e..b07da1d 100644 --- a/src/index.ts +++ b/src/index.ts @@ -61,6 +61,20 @@ import { getVendorSecurityReviewDocuments, GetVendorSecurityReviewDocumentsTool, } from "./operations/vendors.js"; +import { + getDocuments, + GetDocumentsTool, + getDocumentById, + GetDocumentByIdTool, + getDocumentControls, + GetDocumentControlsTool, + getDocumentLinks, + GetDocumentLinksTool, + getDocumentUploads, + GetDocumentUploadsTool, + downloadDocumentFile, + DownloadDocumentFileTool, +} from "./operations/documents.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -252,6 +266,48 @@ server.tool( getVendorSecurityReviewDocuments, ); +server.tool( + GetDocumentsTool.name, + GetDocumentsTool.description, + GetDocumentsTool.parameters.shape, + getDocuments, +); + +server.tool( + GetDocumentByIdTool.name, + GetDocumentByIdTool.description, + GetDocumentByIdTool.parameters.shape, + getDocumentById, +); + +server.tool( + GetDocumentControlsTool.name, + GetDocumentControlsTool.description, + GetDocumentControlsTool.parameters.shape, + getDocumentControls, +); + +server.tool( + GetDocumentLinksTool.name, + GetDocumentLinksTool.description, + GetDocumentLinksTool.parameters.shape, + getDocumentLinks, +); + +server.tool( + GetDocumentUploadsTool.name, + GetDocumentUploadsTool.description, + GetDocumentUploadsTool.parameters.shape, + getDocumentUploads, +); + +server.tool( + DownloadDocumentFileTool.name, + DownloadDocumentFileTool.description, + DownloadDocumentFileTool.parameters.shape, + downloadDocumentFile, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/controls.ts b/src/operations/controls.ts index e6577af..be51ff4 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -6,7 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "../global-descriptions.js"; +} from "./global-descriptions.js"; const GetControlsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), diff --git a/src/operations/documents.ts b/src/operations/documents.ts new file mode 100644 index 0000000..a38ab2f --- /dev/null +++ b/src/operations/documents.ts @@ -0,0 +1,309 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, + DOCUMENT_ID_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetDocumentsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetDocumentsTool: Tool = { + name: "get_documents", + description: + "List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls.", + parameters: GetDocumentsInput, +}; + +const GetDocumentByIdInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), +}); + +export const GetDocumentByIdTool: Tool = { + name: "get_document_by_id", + description: + "Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from get_documents response. Returns complete document details including name, type, metadata, and compliance mappings.", + parameters: GetDocumentByIdInput, +}; + +const GetDocumentControlsInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetDocumentControlsTool: Tool = { + name: "get_document_controls", + description: + "List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence.", + parameters: GetDocumentControlsInput, +}; + +const GetDocumentLinksInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetDocumentLinksTool: Tool = { + name: "get_document_links", + description: + "List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence.", + parameters: GetDocumentLinksInput, +}; + +const GetDocumentUploadsInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetDocumentUploadsTool: Tool = { + name: "get_document_uploads", + description: + "List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation.", + parameters: GetDocumentUploadsInput, +}; + +const DownloadDocumentFileInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + uploadedFileId: z + .string() + .describe( + "Uploaded file ID to download, e.g. 'file-456' or specific uploaded file identifier", + ), +}); + +export const DownloadDocumentFileTool: Tool = { + name: "download_document_file", + description: + "Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed.", + parameters: DownloadDocumentFileInput, +}; + +export async function getDocuments( + args: z.infer, +): Promise { + const url = new URL("/v1/documents", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getDocumentById( + args: z.infer, +): Promise { + const url = new URL(`/v1/documents/${args.documentId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getDocumentControls( + args: z.infer, +): Promise { + const url = new URL(`/v1/documents/${args.documentId}/controls`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getDocumentLinks( + args: z.infer, +): Promise { + const url = new URL(`/v1/documents/${args.documentId}/links`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getDocumentUploads( + args: z.infer, +): Promise { + const url = new URL(`/v1/documents/${args.documentId}/uploads`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function downloadDocumentFile( + args: z.infer, +): Promise { + const url = new URL(`/v1/documents/${args.documentId}/uploads/${args.uploadedFileId}/media`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + // Get the content type from the response headers + const contentType = response.headers.get('content-type') || 'application/octet-stream'; + const contentLength = response.headers.get('content-length'); + + // Handle text-based MIME types - return content that LLMs can process + if (contentType.startsWith('text/') || + contentType.includes('application/json') || + contentType.includes('application/xml') || + contentType.includes('application/javascript') || + contentType.includes('application/csv') || + contentType.includes('text/csv')) { + try { + const textContent = await response.text(); + return { + content: [ + { + type: "text" as const, + text: `File Content (${contentType}):\n\n${textContent}`, + }, + ], + }; + } catch (error) { + return { + content: [ + { + type: "text" as const, + text: `Error reading text content: ${String(error)}`, + }, + ], + }; + } + } + + // For binary files, return metadata instead of raw binary data + return { + content: [ + { + type: "text" as const, + text: `Binary File Information: +MIME Type: ${contentType} +Content Length: ${contentLength ? `${contentLength} bytes` : 'Unknown'} +Document ID: ${args.documentId} +Uploaded File ID: ${args.uploadedFileId} + +Note: This is a binary file (${contentType.split('/')[0]} format) that cannot be displayed as text. Use get_document_uploads to see file metadata, or access the file directly through the Vanta web interface for viewing.`, + }, + ], + }; +} diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index 7b5cf7b..95c7a37 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -6,7 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "../global-descriptions.js"; +} from "./global-descriptions.js"; const GetFrameworksInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), diff --git a/src/global-descriptions.ts b/src/operations/global-descriptions.ts similarity index 69% rename from src/global-descriptions.ts rename to src/operations/global-descriptions.ts index fe628ec..fa6264e 100644 --- a/src/global-descriptions.ts +++ b/src/operations/global-descriptions.ts @@ -2,4 +2,7 @@ export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of tests retur Allowed values: 1–100. Default is 10.`; export const PAGE_CURSOR_DESCRIPTION = `A marker or pointer telling the API where to start fetching items for the -subsequent page in a paginated response. Leave blank to start from the first page.` \ No newline at end of file +subsequent page in a paginated response. Leave blank to start from the first page.`; + +export const DOCUMENT_ID_DESCRIPTION = + "Document ID to operate on, e.g. 'document-123' or specific document identifier"; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index b112dfc..2d884d4 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -6,7 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "../global-descriptions.js"; +} from "./global-descriptions.js"; const GetIntegrationsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), diff --git a/src/operations/risks.ts b/src/operations/risks.ts index cabca71..cae90e6 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -6,7 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "../global-descriptions.js"; +} from "./global-descriptions.js"; const GetRisksInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), diff --git a/src/operations/tests.ts b/src/operations/tests.ts index cf95a6a..2a13772 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -6,7 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "../global-descriptions.js"; +} from "./global-descriptions.js"; export async function getTests( args: z.infer, diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index 247a5b3..a4940ea 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -6,7 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "../global-descriptions.js"; +} from "./global-descriptions.js"; const GetVendorsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), From 9ae8d09fb8f9f8fa91f30364c69447288f11fb03 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 16:49:46 -0400 Subject: [PATCH 08/24] Add support for Policies endpoints --- README.md | 9 ++++ src/eval/README.md | 8 ++-- src/eval/eval.ts | 32 +++++++++++++ src/index.ts | 20 ++++++++ src/operations/policies.ts | 93 ++++++++++++++++++++++++++++++++++++++ 5 files changed, 159 insertions(+), 3 deletions(-) create mode 100644 src/operations/policies.ts diff --git a/README.md b/README.md index ddf0925..b2a48c8 100644 --- a/README.md +++ b/README.md @@ -64,6 +64,13 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all files and uploads attached to documents for compliance documentation - Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata +### Policy Management + +- List all policies in your Vanta account for compliance and governance management +- Get detailed policy information including content, approval status, and compliance mappings +- Access organizational policies for security, privacy, and operational governance +- View policy metadata including names, types, and associated compliance frameworks + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -105,6 +112,8 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_document_links` | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | | `get_document_uploads` | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | | `download_document_file` | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | +| `get_policies` | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | +| `get_policy_by_id` | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 1d8aa94..62f3527 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 25 test cases covering: +The evaluation includes 27 test cases covering: ### ✅ **Tool Selection Tests** @@ -67,6 +67,8 @@ The evaluation includes 25 test cases covering: - **Document Links**: `get_document_links` for external references in documents - **Document Uploads**: `get_document_uploads` for file uploads attached to documents - **Document Downloads**: `download_document_file` for intelligently downloading files (text content for readable files, metadata for binary files) +- **Policy Listing**: `get_policies` for all organizational policies +- **Policy Details**: `get_policy_by_id` for specific policy information ### ❌ **Negative Tests** @@ -91,8 +93,8 @@ The evaluation includes 25 test cases covering: 📊 Final Results ================ -✅ Passed: 25/25 tests -❌ Failed: 0/25 tests +✅ Passed: 27/27 tests +❌ Failed: 0/27 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 4d7d541..6674677 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -30,6 +30,10 @@ import { GetDocumentUploadsTool, DownloadDocumentFileTool, } from "../operations/documents.js"; +import { + GetPoliciesTool, + GetPolicyByIdTool, +} from "../operations/policies.js"; // Format all tools for OpenAI const tools = [ @@ -209,6 +213,22 @@ const tools = [ parameters: zodToJsonSchema(DownloadDocumentFileTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetPoliciesTool.name, + description: GetPoliciesTool.description, + parameters: zodToJsonSchema(GetPoliciesTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetPolicyByIdTool.name, + description: GetPolicyByIdTool.description, + parameters: zodToJsonSchema(GetPolicyByIdTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -372,6 +392,18 @@ const testCases: TestCase[] = [ expectedParams: { documentId: "DOC-789", uploadedFileId: "FILE-456" }, description: "Should call download_document_file to download specific file from document", }, + { + prompt: "Show me all the policies we have established for our organization.", + expectedTool: "get_policies", + expectedParams: {}, + description: "Should call get_policies to list all organizational policies", + }, + { + prompt: "I need to review the details of our data retention policy with ID POLICY-789.", + expectedTool: "get_policy_by_id", + expectedParams: { policyId: "POLICY-789" }, + description: "Should call get_policy_by_id for specific policy details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index b07da1d..733e7c8 100644 --- a/src/index.ts +++ b/src/index.ts @@ -75,6 +75,12 @@ import { downloadDocumentFile, DownloadDocumentFileTool, } from "./operations/documents.js"; +import { + getPolicies, + GetPoliciesTool, + getPolicyById, + GetPolicyByIdTool, +} from "./operations/policies.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -308,6 +314,20 @@ server.tool( downloadDocumentFile, ); +server.tool( + GetPoliciesTool.name, + GetPoliciesTool.description, + GetPoliciesTool.parameters.shape, + getPolicies, +); + +server.tool( + GetPolicyByIdTool.name, + GetPolicyByIdTool.description, + GetPolicyByIdTool.parameters.shape, + getPolicyById, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/policies.ts b/src/operations/policies.ts new file mode 100644 index 0000000..5fc3b60 --- /dev/null +++ b/src/operations/policies.ts @@ -0,0 +1,93 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetPoliciesInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetPoliciesTool: Tool = { + name: "get_policies", + description: + "List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance.", + parameters: GetPoliciesInput, +}; + +const GetPolicyByIdInput = z.object({ + policyId: z + .string() + .describe( + "Policy ID to retrieve, e.g. 'policy-123' or specific policy identifier", + ), +}); + +export const GetPolicyByIdTool: Tool = { + name: "get_policy_by_id", + description: + "Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings.", + parameters: GetPolicyByIdInput, +}; + +export async function getPolicies( + args: z.infer, +): Promise { + const url = new URL("/v1/policies", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getPolicyById( + args: z.infer, +): Promise { + const url = new URL(`/v1/policies/${args.policyId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 86abc6486bbc80d9ba0e03272fc82b7ac32775d8 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 17:01:11 -0400 Subject: [PATCH 09/24] Add discovered vendors operations and update eval system - Add new discovered-vendors.ts module with tools for listing and managing discovered vendor integrations - Update eval system to include discovered vendors operations in test suite - Update README.md with documentation for discovered vendor endpoints - Register discovered vendor tools in main index.ts --- README.md | 9 +++ src/eval/README.md | 8 ++- src/eval/eval.ts | 32 +++++++++ src/index.ts | 20 ++++++ src/operations/discovered-vendors.ts | 97 ++++++++++++++++++++++++++++ 5 files changed, 163 insertions(+), 3 deletions(-) create mode 100644 src/operations/discovered-vendors.ts diff --git a/README.md b/README.md index b2a48c8..5506bf8 100644 --- a/README.md +++ b/README.md @@ -71,6 +71,13 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access organizational policies for security, privacy, and operational governance - View policy metadata including names, types, and associated compliance frameworks +### Discovered Vendor Management + +- List vendors automatically discovered through integrations for potential vendor onboarding +- Access detailed account information for discovered vendors including integration sources +- Understand vendor relationships and account structures before converting to managed vendors +- Streamline vendor risk assessment workflows by identifying unmanaged vendor relationships + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -114,6 +121,8 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `download_document_file` | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | | `get_policies` | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | | `get_policy_by_id` | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | +| `get_discovered_vendors` | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | +| `get_discovered_vendor_accounts` | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 62f3527..8251723 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 27 test cases covering: +The evaluation includes 29 test cases covering: ### ✅ **Tool Selection Tests** @@ -69,6 +69,8 @@ The evaluation includes 27 test cases covering: - **Document Downloads**: `download_document_file` for intelligently downloading files (text content for readable files, metadata for binary files) - **Policy Listing**: `get_policies` for all organizational policies - **Policy Details**: `get_policy_by_id` for specific policy information +- **Discovered Vendors**: `get_discovered_vendors` for automatically discovered vendors +- **Discovered Vendor Accounts**: `get_discovered_vendor_accounts` for detailed vendor account information ### ❌ **Negative Tests** @@ -93,8 +95,8 @@ The evaluation includes 27 test cases covering: 📊 Final Results ================ -✅ Passed: 27/27 tests -❌ Failed: 0/27 tests +✅ Passed: 29/29 tests +❌ Failed: 0/29 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 6674677..e42a3a8 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -34,6 +34,10 @@ import { GetPoliciesTool, GetPolicyByIdTool, } from "../operations/policies.js"; +import { + GetDiscoveredVendorsTool, + GetDiscoveredVendorAccountsTool, +} from "../operations/discovered-vendors.js"; // Format all tools for OpenAI const tools = [ @@ -229,6 +233,22 @@ const tools = [ parameters: zodToJsonSchema(GetPolicyByIdTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetDiscoveredVendorsTool.name, + description: GetDiscoveredVendorsTool.description, + parameters: zodToJsonSchema(GetDiscoveredVendorsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetDiscoveredVendorAccountsTool.name, + description: GetDiscoveredVendorAccountsTool.description, + parameters: zodToJsonSchema(GetDiscoveredVendorAccountsTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -404,6 +424,18 @@ const testCases: TestCase[] = [ expectedParams: { policyId: "POLICY-789" }, description: "Should call get_policy_by_id for specific policy details", }, + { + prompt: "Show me all the vendors that have been discovered through our integrations but aren't yet managed.", + expectedTool: "get_discovered_vendors", + expectedParams: {}, + description: "Should call get_discovered_vendors to list automatically discovered vendors", + }, + { + prompt: "I need detailed account information for all discovered vendor accounts from our integrations.", + expectedTool: "get_discovered_vendor_accounts", + expectedParams: {}, + description: "Should call get_discovered_vendor_accounts to get detailed vendor account information", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index 733e7c8..daa17d1 100644 --- a/src/index.ts +++ b/src/index.ts @@ -81,6 +81,12 @@ import { getPolicyById, GetPolicyByIdTool, } from "./operations/policies.js"; +import { + getDiscoveredVendors, + GetDiscoveredVendorsTool, + getDiscoveredVendorAccounts, + GetDiscoveredVendorAccountsTool, +} from "./operations/discovered-vendors.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -328,6 +334,20 @@ server.tool( getPolicyById, ); +server.tool( + GetDiscoveredVendorsTool.name, + GetDiscoveredVendorsTool.description, + GetDiscoveredVendorsTool.parameters.shape, + getDiscoveredVendors, +); + +server.tool( + GetDiscoveredVendorAccountsTool.name, + GetDiscoveredVendorAccountsTool.description, + GetDiscoveredVendorAccountsTool.parameters.shape, + getDiscoveredVendorAccounts, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts new file mode 100644 index 0000000..7786094 --- /dev/null +++ b/src/operations/discovered-vendors.ts @@ -0,0 +1,97 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetDiscoveredVendorsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetDiscoveredVendorsTool: Tool = { + name: "get_discovered_vendors", + description: + "List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding.", + parameters: GetDiscoveredVendorsInput, +}; + +const GetDiscoveredVendorAccountsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetDiscoveredVendorAccountsTool: Tool = { + name: "get_discovered_vendor_accounts", + description: + "List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors.", + parameters: GetDiscoveredVendorAccountsInput, +}; + +export async function getDiscoveredVendors( + args: z.infer, +): Promise { + const url = new URL("/v1/discovered-vendors", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getDiscoveredVendorAccounts( + args: z.infer, +): Promise { + const url = new URL("/v1/discovered-vendors/accounts", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From f7712a92586c1d067ef2e85e411de796feb83183 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 17:04:51 -0400 Subject: [PATCH 10/24] Add support for Groups and People endpoints --- README.md | 14 ++++ src/eval/README.md | 11 ++- src/eval/eval.ts | 79 ++++++++++++++++++++++ src/index.ts | 49 ++++++++++++++ src/operations/groups.ts | 142 +++++++++++++++++++++++++++++++++++++++ src/operations/people.ts | 93 +++++++++++++++++++++++++ 6 files changed, 385 insertions(+), 3 deletions(-) create mode 100644 src/operations/groups.ts create mode 100644 src/operations/people.ts diff --git a/README.md b/README.md index 5506bf8..4ae20b2 100644 --- a/README.md +++ b/README.md @@ -78,6 +78,15 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Understand vendor relationships and account structures before converting to managed vendors - Streamline vendor risk assessment workflows by identifying unmanaged vendor relationships +### Group & People Management + +- List all organizational groups for structure and access management +- Get detailed group information including member counts and access permissions +- View group membership to understand who has group-based access permissions +- List all people in your organization for compliance and security management +- Access detailed person information including roles, email addresses, and group memberships +- Manage organizational structure and access control through comprehensive people and group data + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -123,6 +132,11 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_policy_by_id` | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | | `get_discovered_vendors` | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | | `get_discovered_vendor_accounts` | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | +| `get_groups` | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | +| `get_group_by_id` | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from get_groups response. Returns complete group details including name, description, member count, and access permissions. | +| `get_group_people` | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | +| `get_people` | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | +| `get_person_by_id` | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from get_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 8251723..c65774e 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 29 test cases covering: +The evaluation includes 34 test cases covering: ### ✅ **Tool Selection Tests** @@ -71,6 +71,11 @@ The evaluation includes 29 test cases covering: - **Policy Details**: `get_policy_by_id` for specific policy information - **Discovered Vendors**: `get_discovered_vendors` for automatically discovered vendors - **Discovered Vendor Accounts**: `get_discovered_vendor_accounts` for detailed vendor account information +- **Group Listing**: `get_groups` for all organizational groups +- **Group Details**: `get_group_by_id` for specific group information +- **Group Membership**: `get_group_people` for people in specific groups +- **People Listing**: `get_people` for all people in the organization +- **Person Details**: `get_person_by_id` for specific person information ### ❌ **Negative Tests** @@ -95,8 +100,8 @@ The evaluation includes 29 test cases covering: 📊 Final Results ================ -✅ Passed: 29/29 tests -❌ Failed: 0/29 tests +✅ Passed: 34/34 tests +❌ Failed: 0/34 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index e42a3a8..ca219f7 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -38,6 +38,15 @@ import { GetDiscoveredVendorsTool, GetDiscoveredVendorAccountsTool, } from "../operations/discovered-vendors.js"; +import { + GetGroupsTool, + GetGroupByIdTool, + GetGroupPeopleTool, +} from "../operations/groups.js"; +import { + GetPeopleTool, + GetPersonByIdTool, +} from "../operations/people.js"; // Format all tools for OpenAI const tools = [ @@ -249,6 +258,46 @@ const tools = [ parameters: zodToJsonSchema(GetDiscoveredVendorAccountsTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetGroupsTool.name, + description: GetGroupsTool.description, + parameters: zodToJsonSchema(GetGroupsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetGroupByIdTool.name, + description: GetGroupByIdTool.description, + parameters: zodToJsonSchema(GetGroupByIdTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetGroupPeopleTool.name, + description: GetGroupPeopleTool.description, + parameters: zodToJsonSchema(GetGroupPeopleTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetPeopleTool.name, + description: GetPeopleTool.description, + parameters: zodToJsonSchema(GetPeopleTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetPersonByIdTool.name, + description: GetPersonByIdTool.description, + parameters: zodToJsonSchema(GetPersonByIdTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -436,6 +485,36 @@ const testCases: TestCase[] = [ expectedParams: {}, description: "Should call get_discovered_vendor_accounts to get detailed vendor account information", }, + { + prompt: "Show me all the organizational groups we have set up for access management.", + expectedTool: "get_groups", + expectedParams: {}, + description: "Should call get_groups to list all organizational groups", + }, + { + prompt: "I need details about the Engineering group with ID GROUP-456.", + expectedTool: "get_group_by_id", + expectedParams: { groupId: "GROUP-456" }, + description: "Should call get_group_by_id for specific group details", + }, + { + prompt: "Who are all the members of the Security team group?", + expectedTool: "get_group_people", + expectedParams: { groupId: "Security team" }, + description: "Should call get_group_people to list people in a specific group", + }, + { + prompt: "List all people in our organization for the compliance audit.", + expectedTool: "get_people", + expectedParams: {}, + description: "Should call get_people to list all people in the organization", + }, + { + prompt: "Get me the details for employee PERSON-789.", + expectedTool: "get_person_by_id", + expectedParams: { personId: "PERSON-789" }, + description: "Should call get_person_by_id for specific person details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index daa17d1..ac81b77 100644 --- a/src/index.ts +++ b/src/index.ts @@ -87,6 +87,20 @@ import { getDiscoveredVendorAccounts, GetDiscoveredVendorAccountsTool, } from "./operations/discovered-vendors.js"; +import { + getGroups, + GetGroupsTool, + getGroupById, + GetGroupByIdTool, + getGroupPeople, + GetGroupPeopleTool, +} from "./operations/groups.js"; +import { + getPeople, + GetPeopleTool, + getPersonById, + GetPersonByIdTool, +} from "./operations/people.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -348,6 +362,41 @@ server.tool( getDiscoveredVendorAccounts, ); +server.tool( + GetGroupsTool.name, + GetGroupsTool.description, + GetGroupsTool.parameters.shape, + getGroups, +); + +server.tool( + GetGroupByIdTool.name, + GetGroupByIdTool.description, + GetGroupByIdTool.parameters.shape, + getGroupById, +); + +server.tool( + GetGroupPeopleTool.name, + GetGroupPeopleTool.description, + GetGroupPeopleTool.parameters.shape, + getGroupPeople, +); + +server.tool( + GetPeopleTool.name, + GetPeopleTool.description, + GetPeopleTool.parameters.shape, + getPeople, +); + +server.tool( + GetPersonByIdTool.name, + GetPersonByIdTool.description, + GetPersonByIdTool.parameters.shape, + getPersonById, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/groups.ts b/src/operations/groups.ts new file mode 100644 index 0000000..a5c9d9a --- /dev/null +++ b/src/operations/groups.ts @@ -0,0 +1,142 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetGroupsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetGroupsTool: Tool = { + name: "get_groups", + description: + "List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control.", + parameters: GetGroupsInput, +}; + +const GetGroupByIdInput = z.object({ + groupId: z + .string() + .describe( + "Group ID to retrieve, e.g. 'group-123' or specific group identifier", + ), +}); + +export const GetGroupByIdTool: Tool = { + name: "get_group_by_id", + description: + "Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from get_groups response. Returns complete group details including name, description, member count, and access permissions.", + parameters: GetGroupByIdInput, +}; + +const GetGroupPeopleInput = z.object({ + groupId: z + .string() + .describe( + "Group ID to get people for, e.g. 'group-123' or specific group identifier", + ), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetGroupPeopleTool: Tool = { + name: "get_group_people", + description: + "List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions.", + parameters: GetGroupPeopleInput, +}; + +export async function getGroups( + args: z.infer, +): Promise { + const url = new URL("/v1/groups", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getGroupById( + args: z.infer, +): Promise { + const url = new URL(`/v1/groups/${args.groupId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getGroupPeople( + args: z.infer, +): Promise { + const url = new URL(`/v1/groups/${args.groupId}/people`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} diff --git a/src/operations/people.ts b/src/operations/people.ts new file mode 100644 index 0000000..93a0518 --- /dev/null +++ b/src/operations/people.ts @@ -0,0 +1,93 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetPeopleInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetPeopleTool: Tool = { + name: "get_people", + description: + "List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management.", + parameters: GetPeopleInput, +}; + +const GetPersonByIdInput = z.object({ + personId: z + .string() + .describe( + "Person ID to retrieve, e.g. 'person-123' or specific person identifier", + ), +}); + +export const GetPersonByIdTool: Tool = { + name: "get_person_by_id", + description: + "Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from get_people response. Returns complete person details including name, email, role, group memberships, and access permissions.", + parameters: GetPersonByIdInput, +}; + +export async function getPeople( + args: z.infer, +): Promise { + const url = new URL("/v1/people", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getPersonById( + args: z.infer, +): Promise { + const url = new URL(`/v1/people/${args.personId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 05babe306df817bdaed2ed3b69923eac16a3e197 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 17:10:31 -0400 Subject: [PATCH 11/24] Add support for Vulnerabilities endpoints - Add new vulnerabilities.ts module with tools for listing and managing vulnerabilities - Add new vulnerability-remediations.ts module with tools for listing and managing vulnerability remediations - Add new vulnerable-assets.ts module with tools for listing and managing vulnerable assets - Update eval system to include vulnerabilities operations in test suite - Update README.md with documentation for vulnerabilities endpoints - Register vulnerabilities tools in main index.ts --- README.md | 13 +++ src/eval/README.md | 11 ++- src/eval/eval.ts | 81 +++++++++++++++++ src/index.ts | 51 +++++++++++ src/operations/vulnerabilities.ts | 93 ++++++++++++++++++++ src/operations/vulnerability-remediations.ts | 53 +++++++++++ src/operations/vulnerable-assets.ts | 93 ++++++++++++++++++++ 7 files changed, 392 insertions(+), 3 deletions(-) create mode 100644 src/operations/vulnerabilities.ts create mode 100644 src/operations/vulnerability-remediations.ts create mode 100644 src/operations/vulnerable-assets.ts diff --git a/README.md b/README.md index 4ae20b2..6b474d1 100644 --- a/README.md +++ b/README.md @@ -87,6 +87,14 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access detailed person information including roles, email addresses, and group memberships - Manage organizational structure and access control through comprehensive people and group data +### Vulnerability Management + +- Monitor all vulnerabilities detected across your infrastructure and applications +- Access detailed vulnerability information including CVE data, severity levels, and affected assets +- Track vulnerability remediation efforts and timelines for security management +- Identify vulnerable assets and understand their security status +- Prioritize security efforts based on asset vulnerability associations and risk levels + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -137,6 +145,11 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_group_people` | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | | `get_people` | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | | `get_person_by_id` | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from get_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | +| `get_vulnerabilities` | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | +| `get_vulnerability_by_id` | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from get_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | +| `get_vulnerability_remediations` | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | +| `get_vulnerable_assets` | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | +| `get_vulnerable_asset_by_id` | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index c65774e..261ba68 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 34 test cases covering: +The evaluation includes 39 test cases covering: ### ✅ **Tool Selection Tests** @@ -76,6 +76,11 @@ The evaluation includes 34 test cases covering: - **Group Membership**: `get_group_people` for people in specific groups - **People Listing**: `get_people` for all people in the organization - **Person Details**: `get_person_by_id` for specific person information +- **Vulnerability Listing**: `get_vulnerabilities` for all detected vulnerabilities +- **Vulnerability Details**: `get_vulnerability_by_id` for specific vulnerability information +- **Vulnerability Remediations**: `get_vulnerability_remediations` for tracking remediation efforts +- **Vulnerable Assets**: `get_vulnerable_assets` for assets affected by vulnerabilities +- **Vulnerable Asset Details**: `get_vulnerable_asset_by_id` for specific asset vulnerability information ### ❌ **Negative Tests** @@ -100,8 +105,8 @@ The evaluation includes 34 test cases covering: 📊 Final Results ================ -✅ Passed: 34/34 tests -❌ Failed: 0/34 tests +✅ Passed: 39/39 tests +❌ Failed: 0/39 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index ca219f7..d59b7f5 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -47,6 +47,17 @@ import { GetPeopleTool, GetPersonByIdTool, } from "../operations/people.js"; +import { + GetVulnerabilitiesTool, + GetVulnerabilityByIdTool, +} from "../operations/vulnerabilities.js"; +import { + GetVulnerabilityRemediationsTool, +} from "../operations/vulnerability-remediations.js"; +import { + GetVulnerableAssetsTool, + GetVulnerableAssetByIdTool, +} from "../operations/vulnerable-assets.js"; // Format all tools for OpenAI const tools = [ @@ -298,6 +309,46 @@ const tools = [ parameters: zodToJsonSchema(GetPersonByIdTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetVulnerabilitiesTool.name, + description: GetVulnerabilitiesTool.description, + parameters: zodToJsonSchema(GetVulnerabilitiesTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVulnerabilityByIdTool.name, + description: GetVulnerabilityByIdTool.description, + parameters: zodToJsonSchema(GetVulnerabilityByIdTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVulnerabilityRemediationsTool.name, + description: GetVulnerabilityRemediationsTool.description, + parameters: zodToJsonSchema(GetVulnerabilityRemediationsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVulnerableAssetsTool.name, + description: GetVulnerableAssetsTool.description, + parameters: zodToJsonSchema(GetVulnerableAssetsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVulnerableAssetByIdTool.name, + description: GetVulnerableAssetByIdTool.description, + parameters: zodToJsonSchema(GetVulnerableAssetByIdTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -515,6 +566,36 @@ const testCases: TestCase[] = [ expectedParams: { personId: "PERSON-789" }, description: "Should call get_person_by_id for specific person details", }, + { + prompt: "Show me all the security vulnerabilities detected in our infrastructure.", + expectedTool: "get_vulnerabilities", + expectedParams: {}, + description: "Should call get_vulnerabilities to list all detected vulnerabilities", + }, + { + prompt: "I need detailed information about vulnerability VULN-456 including its CVE data.", + expectedTool: "get_vulnerability_by_id", + expectedParams: { vulnerabilityId: "VULN-456" }, + description: "Should call get_vulnerability_by_id for specific vulnerability details", + }, + { + prompt: "What vulnerability remediations are currently in progress?", + expectedTool: "get_vulnerability_remediations", + expectedParams: {}, + description: "Should call get_vulnerability_remediations to track remediation efforts", + }, + { + prompt: "List all assets that are affected by vulnerabilities for our security review.", + expectedTool: "get_vulnerable_assets", + expectedParams: {}, + description: "Should call get_vulnerable_assets to identify affected infrastructure", + }, + { + prompt: "Get details about vulnerable asset ASSET-789 and its security status.", + expectedTool: "get_vulnerable_asset_by_id", + expectedParams: { vulnerableAssetId: "ASSET-789" }, + description: "Should call get_vulnerable_asset_by_id for specific asset vulnerability details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index ac81b77..c2cf08a 100644 --- a/src/index.ts +++ b/src/index.ts @@ -101,6 +101,22 @@ import { getPersonById, GetPersonByIdTool, } from "./operations/people.js"; +import { + getVulnerabilities, + GetVulnerabilitiesTool, + getVulnerabilityById, + GetVulnerabilityByIdTool, +} from "./operations/vulnerabilities.js"; +import { + getVulnerabilityRemediations, + GetVulnerabilityRemediationsTool, +} from "./operations/vulnerability-remediations.js"; +import { + getVulnerableAssets, + GetVulnerableAssetsTool, + getVulnerableAssetById, + GetVulnerableAssetByIdTool, +} from "./operations/vulnerable-assets.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -397,6 +413,41 @@ server.tool( getPersonById, ); +server.tool( + GetVulnerabilitiesTool.name, + GetVulnerabilitiesTool.description, + GetVulnerabilitiesTool.parameters.shape, + getVulnerabilities, +); + +server.tool( + GetVulnerabilityByIdTool.name, + GetVulnerabilityByIdTool.description, + GetVulnerabilityByIdTool.parameters.shape, + getVulnerabilityById, +); + +server.tool( + GetVulnerabilityRemediationsTool.name, + GetVulnerabilityRemediationsTool.description, + GetVulnerabilityRemediationsTool.parameters.shape, + getVulnerabilityRemediations, +); + +server.tool( + GetVulnerableAssetsTool.name, + GetVulnerableAssetsTool.description, + GetVulnerableAssetsTool.parameters.shape, + getVulnerableAssets, +); + +server.tool( + GetVulnerableAssetByIdTool.name, + GetVulnerableAssetByIdTool.description, + GetVulnerableAssetByIdTool.parameters.shape, + getVulnerableAssetById, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts new file mode 100644 index 0000000..4593f00 --- /dev/null +++ b/src/operations/vulnerabilities.ts @@ -0,0 +1,93 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetVulnerabilitiesInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVulnerabilitiesTool: Tool = { + name: "get_vulnerabilities", + description: + "Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications.", + parameters: GetVulnerabilitiesInput, +}; + +const GetVulnerabilityByIdInput = z.object({ + vulnerabilityId: z + .string() + .describe( + "Vulnerability ID to retrieve, e.g. 'vuln-123' or specific vulnerability identifier", + ), +}); + +export const GetVulnerabilityByIdTool: Tool = { + name: "get_vulnerability_by_id", + description: + "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from get_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status.", + parameters: GetVulnerabilityByIdInput, +}; + +export async function getVulnerabilities( + args: z.infer, +): Promise { + const url = new URL("/v1/vulnerabilities", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVulnerabilityById( + args: z.infer, +): Promise { + const url = new URL(`/v1/vulnerabilities/${args.vulnerabilityId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} diff --git a/src/operations/vulnerability-remediations.ts b/src/operations/vulnerability-remediations.ts new file mode 100644 index 0000000..bf01622 --- /dev/null +++ b/src/operations/vulnerability-remediations.ts @@ -0,0 +1,53 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetVulnerabilityRemediationsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVulnerabilityRemediationsTool: Tool = { + name: "get_vulnerability_remediations", + description: + "List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues.", + parameters: GetVulnerabilityRemediationsInput, +}; + +export async function getVulnerabilityRemediations( + args: z.infer, +): Promise { + const url = new URL("/v1/vulnerability-remediations", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts new file mode 100644 index 0000000..d0df665 --- /dev/null +++ b/src/operations/vulnerable-assets.ts @@ -0,0 +1,93 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetVulnerableAssetsInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVulnerableAssetsTool: Tool = { + name: "get_vulnerable_assets", + description: + "List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts.", + parameters: GetVulnerableAssetsInput, +}; + +const GetVulnerableAssetByIdInput = z.object({ + vulnerableAssetId: z + .string() + .describe( + "Vulnerable asset ID to retrieve, e.g. 'asset-123' or specific vulnerable asset identifier", + ), +}); + +export const GetVulnerableAssetByIdTool: Tool = { + name: "get_vulnerable_asset_by_id", + description: + "Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status.", + parameters: GetVulnerableAssetByIdInput, +}; + +export async function getVulnerableAssets( + args: z.infer, +): Promise { + const url = new URL("/v1/vulnerable-assets", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getVulnerableAssetById( + args: z.infer, +): Promise { + const url = new URL(`/v1/vulnerable-assets/${args.vulnerableAssetId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From fa673c82fee48f16901cebe09ebede90c870c1bc Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 17:13:59 -0400 Subject: [PATCH 12/24] Add support for Monitored Computers and Vendor Risk Attributes endpoints - Add new monitored-computers.ts module with tools for listing and managing monitored computers - Add new vendor-risk-attributes.ts module with tools for listing and managing vendor risk attributes - Update eval system to include monitored computers and vendor risk attributes operations in test suite - Update README.md with documentation for monitored computers and vendor risk attributes endpoints - Register monitored computers and vendor risk attributes tools in main index.ts --- README.md | 11 +++ src/eval/README.md | 9 ++- src/eval/eval.ts | 49 +++++++++++++ src/index.ts | 31 ++++++++ src/operations/monitored-computers.ts | 93 ++++++++++++++++++++++++ src/operations/vendor-risk-attributes.ts | 53 ++++++++++++++ 6 files changed, 243 insertions(+), 3 deletions(-) create mode 100644 src/operations/monitored-computers.ts create mode 100644 src/operations/vendor-risk-attributes.ts diff --git a/README.md b/README.md index 6b474d1..d3ae69f 100644 --- a/README.md +++ b/README.md @@ -95,6 +95,14 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Identify vulnerable assets and understand their security status - Prioritize security efforts based on asset vulnerability associations and risk levels +### Endpoint & Risk Management + +- Monitor all computers across your organization for compliance and security +- Access detailed computer information including hostnames, operating systems, and security status +- Manage endpoint security and compliance across diverse computing environments +- Understand available vendor risk attributes for comprehensive risk assessment +- Categorize and evaluate vendor risks using standardized risk assessment criteria + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -150,6 +158,9 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_vulnerability_remediations` | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | | `get_vulnerable_assets` | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | | `get_vulnerable_asset_by_id` | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | +| `get_monitored_computers` | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | +| `get_monitored_computer_by_id` | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | +| `get_vendor_risk_attributes` | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index 261ba68..ee9f942 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 39 test cases covering: +The evaluation includes 42 test cases covering: ### ✅ **Tool Selection Tests** @@ -81,6 +81,9 @@ The evaluation includes 39 test cases covering: - **Vulnerability Remediations**: `get_vulnerability_remediations` for tracking remediation efforts - **Vulnerable Assets**: `get_vulnerable_assets` for assets affected by vulnerabilities - **Vulnerable Asset Details**: `get_vulnerable_asset_by_id` for specific asset vulnerability information +- **Monitored Computers**: `get_monitored_computers` for all computers being monitored for compliance +- **Computer Details**: `get_monitored_computer_by_id` for specific computer information +- **Vendor Risk Attributes**: `get_vendor_risk_attributes` for available risk assessment criteria ### ❌ **Negative Tests** @@ -105,8 +108,8 @@ The evaluation includes 39 test cases covering: 📊 Final Results ================ -✅ Passed: 39/39 tests -❌ Failed: 0/39 tests +✅ Passed: 42/42 tests +❌ Failed: 0/42 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index d59b7f5..95c3667 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -58,6 +58,13 @@ import { GetVulnerableAssetsTool, GetVulnerableAssetByIdTool, } from "../operations/vulnerable-assets.js"; +import { + GetMonitoredComputersTool, + GetMonitoredComputerByIdTool, +} from "../operations/monitored-computers.js"; +import { + GetVendorRiskAttributesTool, +} from "../operations/vendor-risk-attributes.js"; // Format all tools for OpenAI const tools = [ @@ -349,6 +356,30 @@ const tools = [ parameters: zodToJsonSchema(GetVulnerableAssetByIdTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetMonitoredComputersTool.name, + description: GetMonitoredComputersTool.description, + parameters: zodToJsonSchema(GetMonitoredComputersTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetMonitoredComputerByIdTool.name, + description: GetMonitoredComputerByIdTool.description, + parameters: zodToJsonSchema(GetMonitoredComputerByIdTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetVendorRiskAttributesTool.name, + description: GetVendorRiskAttributesTool.description, + parameters: zodToJsonSchema(GetVendorRiskAttributesTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -596,6 +627,24 @@ const testCases: TestCase[] = [ expectedParams: { vulnerableAssetId: "ASSET-789" }, description: "Should call get_vulnerable_asset_by_id for specific asset vulnerability details", }, + { + prompt: "Show me all the computers being monitored for compliance across our organization.", + expectedTool: "get_monitored_computers", + expectedParams: {}, + description: "Should call get_monitored_computers to list all monitored computers", + }, + { + prompt: "I need details about the monitored computer with ID COMP-456.", + expectedTool: "get_monitored_computer_by_id", + expectedParams: { computerId: "COMP-456" }, + description: "Should call get_monitored_computer_by_id for specific computer details", + }, + { + prompt: "What vendor risk attributes are available for evaluating our vendors?", + expectedTool: "get_vendor_risk_attributes", + expectedParams: {}, + description: "Should call get_vendor_risk_attributes to list available risk assessment criteria", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index c2cf08a..2f7c2ef 100644 --- a/src/index.ts +++ b/src/index.ts @@ -117,6 +117,16 @@ import { getVulnerableAssetById, GetVulnerableAssetByIdTool, } from "./operations/vulnerable-assets.js"; +import { + getMonitoredComputers, + GetMonitoredComputersTool, + getMonitoredComputerById, + GetMonitoredComputerByIdTool, +} from "./operations/monitored-computers.js"; +import { + getVendorRiskAttributes, + GetVendorRiskAttributesTool, +} from "./operations/vendor-risk-attributes.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -448,6 +458,27 @@ server.tool( getVulnerableAssetById, ); +server.tool( + GetMonitoredComputersTool.name, + GetMonitoredComputersTool.description, + GetMonitoredComputersTool.parameters.shape, + getMonitoredComputers, +); + +server.tool( + GetMonitoredComputerByIdTool.name, + GetMonitoredComputerByIdTool.description, + GetMonitoredComputerByIdTool.parameters.shape, + getMonitoredComputerById, +); + +server.tool( + GetVendorRiskAttributesTool.name, + GetVendorRiskAttributesTool.description, + GetVendorRiskAttributesTool.parameters.shape, + getVendorRiskAttributes, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts new file mode 100644 index 0000000..0b3ba38 --- /dev/null +++ b/src/operations/monitored-computers.ts @@ -0,0 +1,93 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetMonitoredComputersInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetMonitoredComputersTool: Tool = { + name: "get_monitored_computers", + description: + "List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization.", + parameters: GetMonitoredComputersInput, +}; + +const GetMonitoredComputerByIdInput = z.object({ + computerId: z + .string() + .describe( + "Computer ID to retrieve, e.g. 'computer-123' or specific computer identifier", + ), +}); + +export const GetMonitoredComputerByIdTool: Tool = { + name: "get_monitored_computer_by_id", + description: + "Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information.", + parameters: GetMonitoredComputerByIdInput, +}; + +export async function getMonitoredComputers( + args: z.infer, +): Promise { + const url = new URL("/v1/monitored-computers", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getMonitoredComputerById( + args: z.infer, +): Promise { + const url = new URL(`/v1/monitored-computers/${args.computerId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} diff --git a/src/operations/vendor-risk-attributes.ts b/src/operations/vendor-risk-attributes.ts new file mode 100644 index 0000000..198416f --- /dev/null +++ b/src/operations/vendor-risk-attributes.ts @@ -0,0 +1,53 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetVendorRiskAttributesInput = z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetVendorRiskAttributesTool: Tool = { + name: "get_vendor_risk_attributes", + description: + "List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization.", + parameters: GetVendorRiskAttributesInput, +}; + +export async function getVendorRiskAttributes( + args: z.infer, +): Promise { + const url = new URL("/v1/vendor-risk-attributes", baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 409cd3fcfef7bc4cb102ba619f577a19b836fcb1 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 19:46:06 -0400 Subject: [PATCH 13/24] Add support for Trust Centers endpoints - Add new trust-centers.ts module with tools for listing and managing trust centers - Update eval system to include trust centers operations in test suite - Update README.md with documentation for trust centers endpoints - Register trust centers tools in main index.ts --- README.md | 23 ++ src/eval/README.md | 18 +- src/eval/eval.ts | 182 +++++++++ src/index.ts | 110 ++++++ src/operations/global-descriptions.ts | 3 + src/operations/trust-centers.ts | 522 ++++++++++++++++++++++++++ 6 files changed, 855 insertions(+), 3 deletions(-) create mode 100644 src/operations/trust-centers.ts diff --git a/README.md b/README.md index d3ae69f..f491e5f 100644 --- a/README.md +++ b/README.md @@ -103,6 +103,17 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Understand available vendor risk attributes for comprehensive risk assessment - Categorize and evaluate vendor risks using standardized risk assessment criteria +### Trust Center Management + +- Access complete Trust Center configuration, branding, and public visibility settings +- Manage Trust Center access requests from potential customers and stakeholders +- Track detailed viewer activity and engagement analytics across Trust Center content +- Organize and manage control categories for clear compliance presentation +- Publish and manage compliance controls with implementation details and evidence +- Maintain comprehensive FAQ sections for customer transparency and communication +- Provide downloadable resources including compliance documents and certifications +- Enable customer self-service access to compliance and security information + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -161,6 +172,18 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | `get_monitored_computers` | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | | `get_monitored_computer_by_id` | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | | `get_vendor_risk_attributes` | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | +| `get_trust_center` | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | +| `get_trust_center_access_requests` | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | +| `get_trust_center_access_request` | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | +| `get_trust_center_viewer_activity_events` | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | +| `get_trust_center_control_categories` | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | +| `get_trust_center_control_category` | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | +| `get_trust_center_controls` | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | +| `get_trust_center_control` | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | +| `get_trust_center_faqs` | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | +| `get_trust_center_faq` | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | +| `get_trust_center_resources` | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | +| `get_trust_center_document` | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | ## Configuration diff --git a/src/eval/README.md b/src/eval/README.md index ee9f942..cebf6c6 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 42 test cases covering: +The evaluation includes 54 test cases covering: ### ✅ **Tool Selection Tests** @@ -84,6 +84,18 @@ The evaluation includes 42 test cases covering: - **Monitored Computers**: `get_monitored_computers` for all computers being monitored for compliance - **Computer Details**: `get_monitored_computer_by_id` for specific computer information - **Vendor Risk Attributes**: `get_vendor_risk_attributes` for available risk assessment criteria +- **Trust Center Configuration**: `get_trust_center` for Trust Center settings and branding +- **Trust Center Access Requests**: `get_trust_center_access_requests` for managing customer access +- **Access Request Details**: `get_trust_center_access_request` for individual request information +- **Trust Center Analytics**: `get_trust_center_viewer_activity_events` for engagement tracking +- **Control Categories**: `get_trust_center_control_categories` for compliance organization +- **Category Details**: `get_trust_center_control_category` for specific category information +- **Published Controls**: `get_trust_center_controls` for public compliance controls +- **Control Details**: `get_trust_center_control` for specific control implementation +- **Trust Center FAQs**: `get_trust_center_faqs` for customer information +- **FAQ Details**: `get_trust_center_faq` for specific FAQ content +- **Trust Center Resources**: `get_trust_center_resources` for downloadable materials +- **Resource Documents**: `get_trust_center_document` for specific document details ### ❌ **Negative Tests** @@ -108,8 +120,8 @@ The evaluation includes 42 test cases covering: 📊 Final Results ================ -✅ Passed: 42/42 tests -❌ Failed: 0/42 tests +✅ Passed: 54/54 tests +❌ Failed: 0/54 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 95c3667..d8087d4 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -65,6 +65,20 @@ import { import { GetVendorRiskAttributesTool, } from "../operations/vendor-risk-attributes.js"; +import { + GetTrustCenterTool, + GetTrustCenterAccessRequestsTool, + GetTrustCenterAccessRequestTool, + GetTrustCenterViewerActivityEventsTool, + GetTrustCenterControlCategoriesTool, + GetTrustCenterControlCategoryTool, + GetTrustCenterControlsTool, + GetTrustCenterControlTool, + GetTrustCenterFaqsTool, + GetTrustCenterFaqTool, + GetTrustCenterResourcesTool, + GetTrustCenterDocumentTool, +} from "../operations/trust-centers.js"; // Format all tools for OpenAI const tools = [ @@ -380,6 +394,102 @@ const tools = [ parameters: zodToJsonSchema(GetVendorRiskAttributesTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetTrustCenterTool.name, + description: GetTrustCenterTool.description, + parameters: zodToJsonSchema(GetTrustCenterTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterAccessRequestsTool.name, + description: GetTrustCenterAccessRequestsTool.description, + parameters: zodToJsonSchema(GetTrustCenterAccessRequestsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterAccessRequestTool.name, + description: GetTrustCenterAccessRequestTool.description, + parameters: zodToJsonSchema(GetTrustCenterAccessRequestTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterViewerActivityEventsTool.name, + description: GetTrustCenterViewerActivityEventsTool.description, + parameters: zodToJsonSchema(GetTrustCenterViewerActivityEventsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterControlCategoriesTool.name, + description: GetTrustCenterControlCategoriesTool.description, + parameters: zodToJsonSchema(GetTrustCenterControlCategoriesTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterControlCategoryTool.name, + description: GetTrustCenterControlCategoryTool.description, + parameters: zodToJsonSchema(GetTrustCenterControlCategoryTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterControlsTool.name, + description: GetTrustCenterControlsTool.description, + parameters: zodToJsonSchema(GetTrustCenterControlsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterControlTool.name, + description: GetTrustCenterControlTool.description, + parameters: zodToJsonSchema(GetTrustCenterControlTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterFaqsTool.name, + description: GetTrustCenterFaqsTool.description, + parameters: zodToJsonSchema(GetTrustCenterFaqsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterFaqTool.name, + description: GetTrustCenterFaqTool.description, + parameters: zodToJsonSchema(GetTrustCenterFaqTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterResourcesTool.name, + description: GetTrustCenterResourcesTool.description, + parameters: zodToJsonSchema(GetTrustCenterResourcesTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterDocumentTool.name, + description: GetTrustCenterDocumentTool.description, + parameters: zodToJsonSchema(GetTrustCenterDocumentTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -645,6 +755,78 @@ const testCases: TestCase[] = [ expectedParams: {}, description: "Should call get_vendor_risk_attributes to list available risk assessment criteria", }, + { + prompt: "Show me the configuration and settings for our Trust Center 'acme-security'.", + expectedTool: "get_trust_center", + expectedParams: { slugId: "acme-security" }, + description: "Should call get_trust_center to get Trust Center configuration details", + }, + { + prompt: "List all pending access requests for our Trust Center.", + expectedTool: "get_trust_center_access_requests", + expectedParams: { slugId: "our-trust-center" }, + description: "Should call get_trust_center_access_requests to review access requests", + }, + { + prompt: "Get details about Trust Center access request REQ-789.", + expectedTool: "get_trust_center_access_request", + expectedParams: { slugId: "trust-center", accessRequestId: "REQ-789" }, + description: "Should call get_trust_center_access_request for specific request details", + }, + { + prompt: "What viewer activity has occurred on our Trust Center this month?", + expectedTool: "get_trust_center_viewer_activity_events", + expectedParams: { slugId: "our-trust-center" }, + description: "Should call get_trust_center_viewer_activity_events to track engagement analytics", + }, + { + prompt: "Show me all the control categories in our Trust Center.", + expectedTool: "get_trust_center_control_categories", + expectedParams: { slugId: "trust-center" }, + description: "Should call get_trust_center_control_categories to list control organization", + }, + { + prompt: "Get details about Trust Center control category CAT-456.", + expectedTool: "get_trust_center_control_category", + expectedParams: { slugId: "trust-center", controlCategoryId: "CAT-456" }, + description: "Should call get_trust_center_control_category for specific category details", + }, + { + prompt: "List all the controls published in our public Trust Center.", + expectedTool: "get_trust_center_controls", + expectedParams: { slugId: "public-trust-center" }, + description: "Should call get_trust_center_controls to see published compliance controls", + }, + { + prompt: "Get implementation details for Trust Center control TC-CTRL-123.", + expectedTool: "get_trust_center_control", + expectedParams: { slugId: "trust-center", trustCenterControlId: "TC-CTRL-123" }, + description: "Should call get_trust_center_control for specific control implementation details", + }, + { + prompt: "What FAQs are available on our Trust Center for customers?", + expectedTool: "get_trust_center_faqs", + expectedParams: { slugId: "customer-trust-center" }, + description: "Should call get_trust_center_faqs to list customer information", + }, + { + prompt: "Show me the details of FAQ FAQ-789 from our Trust Center.", + expectedTool: "get_trust_center_faq", + expectedParams: { slugId: "trust-center", faqId: "FAQ-789" }, + description: "Should call get_trust_center_faq for specific FAQ content", + }, + { + prompt: "What compliance documents and resources are available for download on our Trust Center?", + expectedTool: "get_trust_center_resources", + expectedParams: { slugId: "compliance-center" }, + description: "Should call get_trust_center_resources to list downloadable materials", + }, + { + prompt: "Get details about the SOC2 report document DOC-456 on our Trust Center.", + expectedTool: "get_trust_center_document", + expectedParams: { slugId: "trust-center", trustCenterDocumentId: "DOC-456" }, + description: "Should call get_trust_center_document for specific document details", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index 2f7c2ef..f6e9f13 100644 --- a/src/index.ts +++ b/src/index.ts @@ -127,6 +127,32 @@ import { getVendorRiskAttributes, GetVendorRiskAttributesTool, } from "./operations/vendor-risk-attributes.js"; +import { + getTrustCenter, + GetTrustCenterTool, + getTrustCenterAccessRequests, + GetTrustCenterAccessRequestsTool, + getTrustCenterAccessRequest, + GetTrustCenterAccessRequestTool, + getTrustCenterViewerActivityEvents, + GetTrustCenterViewerActivityEventsTool, + getTrustCenterControlCategories, + GetTrustCenterControlCategoriesTool, + getTrustCenterControlCategory, + GetTrustCenterControlCategoryTool, + getTrustCenterControls, + GetTrustCenterControlsTool, + getTrustCenterControl, + GetTrustCenterControlTool, + getTrustCenterFaqs, + GetTrustCenterFaqsTool, + getTrustCenterFaq, + GetTrustCenterFaqTool, + getTrustCenterResources, + GetTrustCenterResourcesTool, + getTrustCenterDocument, + GetTrustCenterDocumentTool, +} from "./operations/trust-centers.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ @@ -479,6 +505,90 @@ server.tool( getVendorRiskAttributes, ); +server.tool( + GetTrustCenterTool.name, + GetTrustCenterTool.description, + GetTrustCenterTool.parameters.shape, + getTrustCenter, +); + +server.tool( + GetTrustCenterAccessRequestsTool.name, + GetTrustCenterAccessRequestsTool.description, + GetTrustCenterAccessRequestsTool.parameters.shape, + getTrustCenterAccessRequests, +); + +server.tool( + GetTrustCenterAccessRequestTool.name, + GetTrustCenterAccessRequestTool.description, + GetTrustCenterAccessRequestTool.parameters.shape, + getTrustCenterAccessRequest, +); + +server.tool( + GetTrustCenterViewerActivityEventsTool.name, + GetTrustCenterViewerActivityEventsTool.description, + GetTrustCenterViewerActivityEventsTool.parameters.shape, + getTrustCenterViewerActivityEvents, +); + +server.tool( + GetTrustCenterControlCategoriesTool.name, + GetTrustCenterControlCategoriesTool.description, + GetTrustCenterControlCategoriesTool.parameters.shape, + getTrustCenterControlCategories, +); + +server.tool( + GetTrustCenterControlCategoryTool.name, + GetTrustCenterControlCategoryTool.description, + GetTrustCenterControlCategoryTool.parameters.shape, + getTrustCenterControlCategory, +); + +server.tool( + GetTrustCenterControlsTool.name, + GetTrustCenterControlsTool.description, + GetTrustCenterControlsTool.parameters.shape, + getTrustCenterControls, +); + +server.tool( + GetTrustCenterControlTool.name, + GetTrustCenterControlTool.description, + GetTrustCenterControlTool.parameters.shape, + getTrustCenterControl, +); + +server.tool( + GetTrustCenterFaqsTool.name, + GetTrustCenterFaqsTool.description, + GetTrustCenterFaqsTool.parameters.shape, + getTrustCenterFaqs, +); + +server.tool( + GetTrustCenterFaqTool.name, + GetTrustCenterFaqTool.description, + GetTrustCenterFaqTool.parameters.shape, + getTrustCenterFaq, +); + +server.tool( + GetTrustCenterResourcesTool.name, + GetTrustCenterResourcesTool.description, + GetTrustCenterResourcesTool.parameters.shape, + getTrustCenterResources, +); + +server.tool( + GetTrustCenterDocumentTool.name, + GetTrustCenterDocumentTool.description, + GetTrustCenterDocumentTool.parameters.shape, + getTrustCenterDocument, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/global-descriptions.ts b/src/operations/global-descriptions.ts index fa6264e..3319ac3 100644 --- a/src/operations/global-descriptions.ts +++ b/src/operations/global-descriptions.ts @@ -6,3 +6,6 @@ subsequent page in a paginated response. Leave blank to start from the first pag export const DOCUMENT_ID_DESCRIPTION = "Document ID to operate on, e.g. 'document-123' or specific document identifier"; + +export const SLUG_ID_DESCRIPTION = + "Slug ID to operate on, e.g. 'my-trust-center' or specific slug identifier"; diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts new file mode 100644 index 0000000..294eb3a --- /dev/null +++ b/src/operations/trust-centers.ts @@ -0,0 +1,522 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { baseApiUrl } from "../api.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { makeAuthenticatedRequest } from "./utils.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, + SLUG_ID_DESCRIPTION, +} from "./global-descriptions.js"; + +const GetTrustCenterInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), +}); + +export const GetTrustCenterTool: Tool = { + name: "get_trust_center", + description: + "Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication.", + parameters: GetTrustCenterInput, +}; + +const GetTrustCenterAccessRequestsInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetTrustCenterAccessRequestsTool: Tool = { + name: "get_trust_center_access_requests", + description: + "List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information.", + parameters: GetTrustCenterAccessRequestsInput, +}; + +const GetTrustCenterAccessRequestInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + accessRequestId: z + .string() + .describe( + "Access request ID to retrieve, e.g. 'request-123' or specific access request identifier", + ), +}); + +export const GetTrustCenterAccessRequestTool: Tool = { + name: "get_trust_center_access_request", + description: + "Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions.", + parameters: GetTrustCenterAccessRequestInput, +}; + +const GetTrustCenterViewerActivityEventsInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetTrustCenterViewerActivityEventsTool: Tool = { + name: "get_trust_center_viewer_activity_events", + description: + "List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics.", + parameters: GetTrustCenterViewerActivityEventsInput, +}; + +const GetTrustCenterControlCategoriesInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetTrustCenterControlCategoriesTool: Tool = { + name: "get_trust_center_control_categories", + description: + "List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors.", + parameters: GetTrustCenterControlCategoriesInput, +}; + +const GetTrustCenterControlCategoryInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + controlCategoryId: z + .string() + .describe( + "Control category ID to retrieve, e.g. 'category-123' or specific control category identifier", + ), +}); + +export const GetTrustCenterControlCategoryTool: Tool = { + name: "get_trust_center_control_category", + description: + "Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management.", + parameters: GetTrustCenterControlCategoryInput, +}; + +const GetTrustCenterControlsInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetTrustCenterControlsTool: Tool = { + name: "get_trust_center_controls", + description: + "List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors.", + parameters: GetTrustCenterControlsInput, +}; + +const GetTrustCenterControlInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + trustCenterControlId: z + .string() + .describe( + "Trust Center control ID to retrieve, e.g. 'tc-control-123' or specific Trust Center control identifier", + ), +}); + +export const GetTrustCenterControlTool: Tool = { + name: "get_trust_center_control", + description: + "Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency.", + parameters: GetTrustCenterControlInput, +}; + +const GetTrustCenterFaqsInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetTrustCenterFaqsTool: Tool = { + name: "get_trust_center_faqs", + description: + "List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section.", + parameters: GetTrustCenterFaqsInput, +}; + +const GetTrustCenterFaqInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + faqId: z + .string() + .describe( + "FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier", + ), +}); + +export const GetTrustCenterFaqTool: Tool = { + name: "get_trust_center_faq", + description: + "Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication.", + parameters: GetTrustCenterFaqInput, +}; + +const GetTrustCenterResourcesInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +}); + +export const GetTrustCenterResourcesTool: Tool = { + name: "get_trust_center_resources", + description: + "List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors.", + parameters: GetTrustCenterResourcesInput, +}; + +const GetTrustCenterDocumentInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + trustCenterDocumentId: z + .string() + .describe( + "Trust Center document ID to retrieve, e.g. 'tc-doc-123' or specific Trust Center document identifier", + ), +}); + +export const GetTrustCenterDocumentTool: Tool = { + name: "get_trust_center_document", + description: + "Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management.", + parameters: GetTrustCenterDocumentInput, +}; + +// Implementation functions +export async function getTrustCenter( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterAccessRequests( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/access-requests`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterAccessRequest( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/access-requests/${args.accessRequestId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterViewerActivityEvents( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/viewer-activity-events`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterControlCategories( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/control-categories`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterControlCategory( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/control-categories/${args.controlCategoryId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterControls( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/controls`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterControl( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/controls/${args.trustCenterControlId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterFaqs( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/faqs`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterFaq( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/faqs/${args.faqId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterResources( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/resources`, baseApiUrl()); + + if (args.pageSize !== undefined) { + url.searchParams.append("pageSize", args.pageSize.toString()); + } + if (args.pageCursor !== undefined) { + url.searchParams.append("pageCursor", args.pageCursor); + } + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +export async function getTrustCenterDocument( + args: z.infer, +): Promise { + const url = new URL(`/v1/trust-centers/${args.slugId}/documents/${args.trustCenterDocumentId}`, baseApiUrl()); + + const response = await makeAuthenticatedRequest(url.toString()); + + if (!response.ok) { + return { + content: [ + { + type: "text" as const, + text: `Error: ${response.statusText}`, + }, + ], + }; + } + + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} From 176a2b02529fcdf066d82738f97b815e5f72cc17 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Tue, 23 Sep 2025 19:55:40 -0400 Subject: [PATCH 14/24] Update controls to use centralized descriptions --- src/operations/controls.ts | 19 +++----------- src/operations/frameworks.ts | 9 +++---- src/operations/global-descriptions.ts | 12 +++++++++ src/operations/integrations.ts | 31 +++++----------------- src/operations/vendors.ts | 37 +++++---------------------- 5 files changed, 32 insertions(+), 76 deletions(-) diff --git a/src/operations/controls.ts b/src/operations/controls.ts index be51ff4..cf56d41 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -6,6 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, + CONTROL_ID_DESCRIPTION, } from "./global-descriptions.js"; const GetControlsInput = z.object({ @@ -27,11 +28,7 @@ export const GetControlsTool: Tool = { }; const GetControlTestsInput = z.object({ - controlId: z - .string() - .describe( - "Control ID to get tests for, e.g. 'access-control-1' or 'data-protection-2'", - ), + controlId: z.string().describe(CONTROL_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -56,11 +53,7 @@ export const GetLibraryControlsTool: Tool = { }; const GetControlDocumentsInput = z.object({ - controlId: z - .string() - .describe( - "Control ID to get documents for, e.g. 'access-control-1' or 'data-protection-2'", - ), + controlId: z.string().describe(CONTROL_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -73,11 +66,7 @@ export const GetControlDocumentsTool: Tool = { }; const GetControlByIdInput = z.object({ - controlId: z - .string() - .describe( - "Control ID to retrieve, e.g. 'access-control-1' or 'data-protection-2'", - ), + controlId: z.string().describe(CONTROL_ID_DESCRIPTION), }); export const GetControlByIdTool: Tool = { diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index 95c7a37..6b52435 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -6,6 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, + FRAMEWORK_ID_DESCRIPTION, } from "./global-descriptions.js"; const GetFrameworksInput = z.object({ @@ -21,7 +22,7 @@ export const GetFrameworksTool: Tool = { }; const GetFrameworkControlsInput = z.object({ - frameworkId: z.string(), + frameworkId: z.string().describe(FRAMEWORK_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -35,11 +36,7 @@ export const GetFrameworkControlsTool: Tool = }; const GetFrameworkByIdInput = z.object({ - frameworkId: z - .string() - .describe( - "Framework ID to retrieve, e.g. 'soc2', 'iso27001', 'hipaa', 'gdpr'", - ), + frameworkId: z.string().describe(FRAMEWORK_ID_DESCRIPTION), }); export const GetFrameworkByIdTool: Tool = { diff --git a/src/operations/global-descriptions.ts b/src/operations/global-descriptions.ts index 3319ac3..70ba9f7 100644 --- a/src/operations/global-descriptions.ts +++ b/src/operations/global-descriptions.ts @@ -4,8 +4,20 @@ Allowed values: 1–100. Default is 10.`; export const PAGE_CURSOR_DESCRIPTION = `A marker or pointer telling the API where to start fetching items for the subsequent page in a paginated response. Leave blank to start from the first page.`; +export const CONTROL_ID_DESCRIPTION = + "Control ID to operate on, e.g. 'control-123' or specific control identifier"; + +export const FRAMEWORK_ID_DESCRIPTION = + "Framework ID to operate on, e.g. 'framework-123' or specific framework identifier"; + export const DOCUMENT_ID_DESCRIPTION = "Document ID to operate on, e.g. 'document-123' or specific document identifier"; +export const INTEGRATION_ID_DESCRIPTION = + "Integration ID to operate on, e.g. 'integration-123' or specific integration identifier"; + export const SLUG_ID_DESCRIPTION = "Slug ID to operate on, e.g. 'my-trust-center' or specific slug identifier"; + +export const VENDOR_ID_DESCRIPTION = + "Vendor ID to operate on, e.g. 'vendor-123' or specific vendor identifier"; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index 2d884d4..a3a2554 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -6,6 +6,7 @@ import { makeAuthenticatedRequest } from "./utils.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, + INTEGRATION_ID_DESCRIPTION, } from "./global-descriptions.js"; const GetIntegrationsInput = z.object({ @@ -21,11 +22,7 @@ export const GetIntegrationsTool: Tool = { }; const GetIntegrationByIdInput = z.object({ - integrationId: z - .string() - .describe( - "Integration ID to retrieve, e.g. 'aws', 'azure', 'gcp', or specific integration identifier", - ), + integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), }); export const GetIntegrationByIdTool: Tool = { @@ -36,11 +33,7 @@ export const GetIntegrationByIdTool: Tool = { }; const GetIntegrationResourceKindsInput = z.object({ - integrationId: z - .string() - .describe( - "Integration ID to get resource kinds for, e.g. 'aws', 'azure', 'gcp'", - ), + integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -53,11 +46,7 @@ export const GetIntegrationResourceKindsTool: Tool = { }; const GetVendorByIdInput = z.object({ - vendorId: z - .string() - .describe( - "Vendor ID to retrieve, e.g. 'vendor-123' or specific vendor identifier", - ), + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), }); export const GetVendorByIdTool: Tool = { @@ -36,11 +33,7 @@ export const GetVendorByIdTool: Tool = { }; const GetVendorDocumentsInput = z.object({ - vendorId: z - .string() - .describe( - "Vendor ID to get documents for, e.g. 'vendor-123' or specific vendor identifier", - ), + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -53,11 +46,7 @@ export const GetVendorDocumentsTool: Tool = { }; const GetVendorFindingsInput = z.object({ - vendorId: z - .string() - .describe( - "Vendor ID to get findings for, e.g. 'vendor-123' or specific vendor identifier", - ), + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -70,11 +59,7 @@ export const GetVendorFindingsTool: Tool = { }; const GetVendorSecurityReviewsInput = z.object({ - vendorId: z - .string() - .describe( - "Vendor ID to get security reviews for, e.g. 'vendor-123' or specific vendor identifier", - ), + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); @@ -87,11 +72,7 @@ export const GetVendorSecurityReviewsTool: Tool Date: Tue, 23 Sep 2025 20:01:58 -0400 Subject: [PATCH 15/24] Update code formatting with Prettier --- src/eval/eval.ts | 191 ++++++++++++------- src/index.ts | 7 +- src/operations/discovered-vendors.ts | 17 +- src/operations/documents.ts | 48 +++-- src/operations/integrations.ts | 36 +++- src/operations/monitored-computers.ts | 13 +- src/operations/trust-centers.ts | 90 ++++++--- src/operations/vendor-risk-attributes.ts | 4 +- src/operations/vendors.ts | 27 ++- src/operations/vulnerabilities.ts | 18 +- src/operations/vulnerability-remediations.ts | 4 +- src/operations/vulnerable-assets.ts | 9 +- 12 files changed, 315 insertions(+), 149 deletions(-) diff --git a/src/eval/eval.ts b/src/eval/eval.ts index d8087d4..15a2df8 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -18,10 +18,7 @@ import { GetIntegrationsTool, GetIntegrationByIdTool, } from "../operations/integrations.js"; -import { - GetVendorsTool, - GetVendorByIdTool, -} from "../operations/vendors.js"; +import { GetVendorsTool, GetVendorByIdTool } from "../operations/vendors.js"; import { GetDocumentsTool, GetDocumentByIdTool, @@ -30,10 +27,7 @@ import { GetDocumentUploadsTool, DownloadDocumentFileTool, } from "../operations/documents.js"; -import { - GetPoliciesTool, - GetPolicyByIdTool, -} from "../operations/policies.js"; +import { GetPoliciesTool, GetPolicyByIdTool } from "../operations/policies.js"; import { GetDiscoveredVendorsTool, GetDiscoveredVendorAccountsTool, @@ -43,17 +37,12 @@ import { GetGroupByIdTool, GetGroupPeopleTool, } from "../operations/groups.js"; -import { - GetPeopleTool, - GetPersonByIdTool, -} from "../operations/people.js"; +import { GetPeopleTool, GetPersonByIdTool } from "../operations/people.js"; import { GetVulnerabilitiesTool, GetVulnerabilityByIdTool, } from "../operations/vulnerabilities.js"; -import { - GetVulnerabilityRemediationsTool, -} from "../operations/vulnerability-remediations.js"; +import { GetVulnerabilityRemediationsTool } from "../operations/vulnerability-remediations.js"; import { GetVulnerableAssetsTool, GetVulnerableAssetByIdTool, @@ -62,9 +51,7 @@ import { GetMonitoredComputersTool, GetMonitoredComputerByIdTool, } from "../operations/monitored-computers.js"; -import { - GetVendorRiskAttributesTool, -} from "../operations/vendor-risk-attributes.js"; +import { GetVendorRiskAttributesTool } from "../operations/vendor-risk-attributes.js"; import { GetTrustCenterTool, GetTrustCenterAccessRequestsTool, @@ -423,7 +410,9 @@ const tools = [ function: { name: GetTrustCenterViewerActivityEventsTool.name, description: GetTrustCenterViewerActivityEventsTool.description, - parameters: zodToJsonSchema(GetTrustCenterViewerActivityEventsTool.parameters), + parameters: zodToJsonSchema( + GetTrustCenterViewerActivityEventsTool.parameters, + ), }, }, { @@ -431,7 +420,9 @@ const tools = [ function: { name: GetTrustCenterControlCategoriesTool.name, description: GetTrustCenterControlCategoriesTool.description, - parameters: zodToJsonSchema(GetTrustCenterControlCategoriesTool.parameters), + parameters: zodToJsonSchema( + GetTrustCenterControlCategoriesTool.parameters, + ), }, }, { @@ -567,7 +558,8 @@ const testCases: TestCase[] = [ prompt: "What controls are available in the Vanta library that I can add?", expectedTool: "get_library_controls", expectedParams: {}, - description: "Should call get_library_controls to list available library controls", + description: + "Should call get_library_controls to list available library controls", }, { prompt: "Show me the documents for control ID access-control-1", @@ -585,25 +577,29 @@ const testCases: TestCase[] = [ prompt: "Show me details for framework ID soc2", expectedTool: "get_framework_by_id", expectedParams: { frameworkId: "soc2" }, - description: "Should call get_framework_by_id for specific framework details", + description: + "Should call get_framework_by_id for specific framework details", }, { prompt: "Get details for risk scenario ID risk-scenario-123", expectedTool: "get_risk_by_id", expectedParams: { riskId: "risk-scenario-123" }, - description: "Should call get_risk_by_id for specific risk scenario details", + description: + "Should call get_risk_by_id for specific risk scenario details", }, { prompt: "What integrations are connected to my Vanta account?", expectedTool: "get_integrations", expectedParams: {}, - description: "Should call get_integrations to list all connected integrations", + description: + "Should call get_integrations to list all connected integrations", }, { prompt: "Show me details for integration ID aws", expectedTool: "get_integration_by_id", expectedParams: { integrationId: "aws" }, - description: "Should call get_integration_by_id for specific integration details", + description: + "Should call get_integration_by_id for specific integration details", }, { prompt: "List all vendors in my Vanta account", @@ -618,13 +614,15 @@ const testCases: TestCase[] = [ description: "Should call get_vendor_by_id for specific vendor details", }, { - prompt: "Show me all the documents we have uploaded to Vanta for compliance purposes.", + prompt: + "Show me all the documents we have uploaded to Vanta for compliance purposes.", expectedTool: "get_documents", expectedParams: {}, description: "Should call get_documents to list all compliance documents", }, { - prompt: "I need to see the details of document DOC-12345 including its metadata and compliance mappings.", + prompt: + "I need to see the details of document DOC-12345 including its metadata and compliance mappings.", expectedTool: "get_document_by_id", expectedParams: { documentId: "DOC-12345" }, description: "Should call get_document_by_id for specific document details", @@ -633,52 +631,65 @@ const testCases: TestCase[] = [ prompt: "Which security controls are mapped to document DOC-789?", expectedTool: "get_document_controls", expectedParams: { documentId: "DOC-789" }, - description: "Should call get_document_controls to find controls associated with document", + description: + "Should call get_document_controls to find controls associated with document", }, { - prompt: "What external links and references are attached to document POLICY-456?", + prompt: + "What external links and references are attached to document POLICY-456?", expectedTool: "get_document_links", expectedParams: { documentId: "POLICY-456" }, - description: "Should call get_document_links to get external references for document", + description: + "Should call get_document_links to get external references for document", }, { prompt: "List all the files uploaded to document SEC-123.", expectedTool: "get_document_uploads", expectedParams: { documentId: "SEC-123" }, - description: "Should call get_document_uploads to list file uploads for document", + description: + "Should call get_document_uploads to list file uploads for document", }, { - prompt: "I need to download the file with uploaded file ID FILE-456 from document DOC-789.", + prompt: + "I need to download the file with uploaded file ID FILE-456 from document DOC-789.", expectedTool: "download_document_file", expectedParams: { documentId: "DOC-789", uploadedFileId: "FILE-456" }, - description: "Should call download_document_file to download specific file from document", + description: + "Should call download_document_file to download specific file from document", }, { - prompt: "Show me all the policies we have established for our organization.", + prompt: + "Show me all the policies we have established for our organization.", expectedTool: "get_policies", expectedParams: {}, description: "Should call get_policies to list all organizational policies", }, { - prompt: "I need to review the details of our data retention policy with ID POLICY-789.", + prompt: + "I need to review the details of our data retention policy with ID POLICY-789.", expectedTool: "get_policy_by_id", expectedParams: { policyId: "POLICY-789" }, description: "Should call get_policy_by_id for specific policy details", }, { - prompt: "Show me all the vendors that have been discovered through our integrations but aren't yet managed.", + prompt: + "Show me all the vendors that have been discovered through our integrations but aren't yet managed.", expectedTool: "get_discovered_vendors", expectedParams: {}, - description: "Should call get_discovered_vendors to list automatically discovered vendors", + description: + "Should call get_discovered_vendors to list automatically discovered vendors", }, { - prompt: "I need detailed account information for all discovered vendor accounts from our integrations.", + prompt: + "I need detailed account information for all discovered vendor accounts from our integrations.", expectedTool: "get_discovered_vendor_accounts", expectedParams: {}, - description: "Should call get_discovered_vendor_accounts to get detailed vendor account information", + description: + "Should call get_discovered_vendor_accounts to get detailed vendor account information", }, { - prompt: "Show me all the organizational groups we have set up for access management.", + prompt: + "Show me all the organizational groups we have set up for access management.", expectedTool: "get_groups", expectedParams: {}, description: "Should call get_groups to list all organizational groups", @@ -693,13 +704,15 @@ const testCases: TestCase[] = [ prompt: "Who are all the members of the Security team group?", expectedTool: "get_group_people", expectedParams: { groupId: "Security team" }, - description: "Should call get_group_people to list people in a specific group", + description: + "Should call get_group_people to list people in a specific group", }, { prompt: "List all people in our organization for the compliance audit.", expectedTool: "get_people", expectedParams: {}, - description: "Should call get_people to list all people in the organization", + description: + "Should call get_people to list all people in the organization", }, { prompt: "Get me the details for employee PERSON-789.", @@ -708,106 +721,133 @@ const testCases: TestCase[] = [ description: "Should call get_person_by_id for specific person details", }, { - prompt: "Show me all the security vulnerabilities detected in our infrastructure.", + prompt: + "Show me all the security vulnerabilities detected in our infrastructure.", expectedTool: "get_vulnerabilities", expectedParams: {}, - description: "Should call get_vulnerabilities to list all detected vulnerabilities", + description: + "Should call get_vulnerabilities to list all detected vulnerabilities", }, { - prompt: "I need detailed information about vulnerability VULN-456 including its CVE data.", + prompt: + "I need detailed information about vulnerability VULN-456 including its CVE data.", expectedTool: "get_vulnerability_by_id", expectedParams: { vulnerabilityId: "VULN-456" }, - description: "Should call get_vulnerability_by_id for specific vulnerability details", + description: + "Should call get_vulnerability_by_id for specific vulnerability details", }, { prompt: "What vulnerability remediations are currently in progress?", expectedTool: "get_vulnerability_remediations", expectedParams: {}, - description: "Should call get_vulnerability_remediations to track remediation efforts", + description: + "Should call get_vulnerability_remediations to track remediation efforts", }, { - prompt: "List all assets that are affected by vulnerabilities for our security review.", + prompt: + "List all assets that are affected by vulnerabilities for our security review.", expectedTool: "get_vulnerable_assets", expectedParams: {}, - description: "Should call get_vulnerable_assets to identify affected infrastructure", + description: + "Should call get_vulnerable_assets to identify affected infrastructure", }, { - prompt: "Get details about vulnerable asset ASSET-789 and its security status.", + prompt: + "Get details about vulnerable asset ASSET-789 and its security status.", expectedTool: "get_vulnerable_asset_by_id", expectedParams: { vulnerableAssetId: "ASSET-789" }, - description: "Should call get_vulnerable_asset_by_id for specific asset vulnerability details", + description: + "Should call get_vulnerable_asset_by_id for specific asset vulnerability details", }, { - prompt: "Show me all the computers being monitored for compliance across our organization.", + prompt: + "Show me all the computers being monitored for compliance across our organization.", expectedTool: "get_monitored_computers", expectedParams: {}, - description: "Should call get_monitored_computers to list all monitored computers", + description: + "Should call get_monitored_computers to list all monitored computers", }, { prompt: "I need details about the monitored computer with ID COMP-456.", expectedTool: "get_monitored_computer_by_id", expectedParams: { computerId: "COMP-456" }, - description: "Should call get_monitored_computer_by_id for specific computer details", + description: + "Should call get_monitored_computer_by_id for specific computer details", }, { - prompt: "What vendor risk attributes are available for evaluating our vendors?", + prompt: + "What vendor risk attributes are available for evaluating our vendors?", expectedTool: "get_vendor_risk_attributes", expectedParams: {}, - description: "Should call get_vendor_risk_attributes to list available risk assessment criteria", + description: + "Should call get_vendor_risk_attributes to list available risk assessment criteria", }, { - prompt: "Show me the configuration and settings for our Trust Center 'acme-security'.", + prompt: + "Show me the configuration and settings for our Trust Center 'acme-security'.", expectedTool: "get_trust_center", expectedParams: { slugId: "acme-security" }, - description: "Should call get_trust_center to get Trust Center configuration details", + description: + "Should call get_trust_center to get Trust Center configuration details", }, { prompt: "List all pending access requests for our Trust Center.", expectedTool: "get_trust_center_access_requests", expectedParams: { slugId: "our-trust-center" }, - description: "Should call get_trust_center_access_requests to review access requests", + description: + "Should call get_trust_center_access_requests to review access requests", }, { prompt: "Get details about Trust Center access request REQ-789.", expectedTool: "get_trust_center_access_request", expectedParams: { slugId: "trust-center", accessRequestId: "REQ-789" }, - description: "Should call get_trust_center_access_request for specific request details", + description: + "Should call get_trust_center_access_request for specific request details", }, { prompt: "What viewer activity has occurred on our Trust Center this month?", expectedTool: "get_trust_center_viewer_activity_events", expectedParams: { slugId: "our-trust-center" }, - description: "Should call get_trust_center_viewer_activity_events to track engagement analytics", + description: + "Should call get_trust_center_viewer_activity_events to track engagement analytics", }, { prompt: "Show me all the control categories in our Trust Center.", expectedTool: "get_trust_center_control_categories", expectedParams: { slugId: "trust-center" }, - description: "Should call get_trust_center_control_categories to list control organization", + description: + "Should call get_trust_center_control_categories to list control organization", }, { prompt: "Get details about Trust Center control category CAT-456.", expectedTool: "get_trust_center_control_category", expectedParams: { slugId: "trust-center", controlCategoryId: "CAT-456" }, - description: "Should call get_trust_center_control_category for specific category details", + description: + "Should call get_trust_center_control_category for specific category details", }, { prompt: "List all the controls published in our public Trust Center.", expectedTool: "get_trust_center_controls", expectedParams: { slugId: "public-trust-center" }, - description: "Should call get_trust_center_controls to see published compliance controls", + description: + "Should call get_trust_center_controls to see published compliance controls", }, { prompt: "Get implementation details for Trust Center control TC-CTRL-123.", expectedTool: "get_trust_center_control", - expectedParams: { slugId: "trust-center", trustCenterControlId: "TC-CTRL-123" }, - description: "Should call get_trust_center_control for specific control implementation details", + expectedParams: { + slugId: "trust-center", + trustCenterControlId: "TC-CTRL-123", + }, + description: + "Should call get_trust_center_control for specific control implementation details", }, { prompt: "What FAQs are available on our Trust Center for customers?", expectedTool: "get_trust_center_faqs", expectedParams: { slugId: "customer-trust-center" }, - description: "Should call get_trust_center_faqs to list customer information", + description: + "Should call get_trust_center_faqs to list customer information", }, { prompt: "Show me the details of FAQ FAQ-789 from our Trust Center.", @@ -816,16 +856,23 @@ const testCases: TestCase[] = [ description: "Should call get_trust_center_faq for specific FAQ content", }, { - prompt: "What compliance documents and resources are available for download on our Trust Center?", + prompt: + "What compliance documents and resources are available for download on our Trust Center?", expectedTool: "get_trust_center_resources", expectedParams: { slugId: "compliance-center" }, - description: "Should call get_trust_center_resources to list downloadable materials", + description: + "Should call get_trust_center_resources to list downloadable materials", }, { - prompt: "Get details about the SOC2 report document DOC-456 on our Trust Center.", + prompt: + "Get details about the SOC2 report document DOC-456 on our Trust Center.", expectedTool: "get_trust_center_document", - expectedParams: { slugId: "trust-center", trustCenterDocumentId: "DOC-456" }, - description: "Should call get_trust_center_document for specific document details", + expectedParams: { + slugId: "trust-center", + trustCenterDocumentId: "DOC-456", + }, + description: + "Should call get_trust_center_document for specific document details", }, { prompt: "What programming tests should I write for my API?", diff --git a/src/index.ts b/src/index.ts index f6e9f13..803f117 100644 --- a/src/index.ts +++ b/src/index.ts @@ -30,7 +30,12 @@ import { getControlDocuments, getControlById, } from "./operations/controls.js"; -import { getRisks, GetRisksTool, getRiskById, GetRiskByIdTool } from "./operations/risks.js"; +import { + getRisks, + GetRisksTool, + getRiskById, + GetRiskByIdTool, +} from "./operations/risks.js"; import { getIntegrations, GetIntegrationsTool, diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts index 7786094..3216aa9 100644 --- a/src/operations/discovered-vendors.ts +++ b/src/operations/discovered-vendors.ts @@ -13,19 +13,22 @@ const GetDiscoveredVendorsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDiscoveredVendorsTool: Tool = { - name: "get_discovered_vendors", - description: - "List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding.", - parameters: GetDiscoveredVendorsInput, -}; +export const GetDiscoveredVendorsTool: Tool = + { + name: "get_discovered_vendors", + description: + "List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding.", + parameters: GetDiscoveredVendorsInput, + }; const GetDiscoveredVendorAccountsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDiscoveredVendorAccountsTool: Tool = { +export const GetDiscoveredVendorAccountsTool: Tool< + typeof GetDiscoveredVendorAccountsInput +> = { name: "get_discovered_vendor_accounts", description: "List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors.", diff --git a/src/operations/documents.ts b/src/operations/documents.ts index a38ab2f..cac24ca 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -80,12 +80,13 @@ const DownloadDocumentFileInput = z.object({ ), }); -export const DownloadDocumentFileTool: Tool = { - name: "download_document_file", - description: - "Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed.", - parameters: DownloadDocumentFileInput, -}; +export const DownloadDocumentFileTool: Tool = + { + name: "download_document_file", + description: + "Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed.", + parameters: DownloadDocumentFileInput, + }; export async function getDocuments( args: z.infer, @@ -147,7 +148,10 @@ export async function getDocumentById( export async function getDocumentControls( args: z.infer, ): Promise { - const url = new URL(`/v1/documents/${args.documentId}/controls`, baseApiUrl()); + const url = new URL( + `/v1/documents/${args.documentId}/controls`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -243,7 +247,10 @@ export async function getDocumentUploads( export async function downloadDocumentFile( args: z.infer, ): Promise { - const url = new URL(`/v1/documents/${args.documentId}/uploads/${args.uploadedFileId}/media`, baseApiUrl()); + const url = new URL( + `/v1/documents/${args.documentId}/uploads/${args.uploadedFileId}/media`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -259,16 +266,19 @@ export async function downloadDocumentFile( } // Get the content type from the response headers - const contentType = response.headers.get('content-type') || 'application/octet-stream'; - const contentLength = response.headers.get('content-length'); - + const contentType = + response.headers.get("content-type") || "application/octet-stream"; + const contentLength = response.headers.get("content-length"); + // Handle text-based MIME types - return content that LLMs can process - if (contentType.startsWith('text/') || - contentType.includes('application/json') || - contentType.includes('application/xml') || - contentType.includes('application/javascript') || - contentType.includes('application/csv') || - contentType.includes('text/csv')) { + if ( + contentType.startsWith("text/") || + contentType.includes("application/json") || + contentType.includes("application/xml") || + contentType.includes("application/javascript") || + contentType.includes("application/csv") || + contentType.includes("text/csv") + ) { try { const textContent = await response.text(); return { @@ -298,11 +308,11 @@ export async function downloadDocumentFile( type: "text" as const, text: `Binary File Information: MIME Type: ${contentType} -Content Length: ${contentLength ? `${contentLength} bytes` : 'Unknown'} +Content Length: ${contentLength ? `${contentLength} bytes` : "Unknown"} Document ID: ${args.documentId} Uploaded File ID: ${args.uploadedFileId} -Note: This is a binary file (${contentType.split('/')[0]} format) that cannot be displayed as text. Use get_document_uploads to see file metadata, or access the file directly through the Vanta web interface for viewing.`, +Note: This is a binary file (${contentType.split("/")[0]} format) that cannot be displayed as text. Use get_document_uploads to see file metadata, or access the file directly through the Vanta web interface for viewing.`, }, ], }; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index a3a2554..ade3539 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -38,7 +38,9 @@ const GetIntegrationResourceKindsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetIntegrationResourceKindsTool: Tool = { +export const GetIntegrationResourceKindsTool: Tool< + typeof GetIntegrationResourceKindsInput +> = { name: "get_integration_resource_kinds", description: "List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor.", @@ -54,7 +56,9 @@ const GetIntegrationResourceKindDetailsInput = z.object({ ), }); -export const GetIntegrationResourceKindDetailsTool: Tool = { +export const GetIntegrationResourceKindDetailsTool: Tool< + typeof GetIntegrationResourceKindDetailsInput +> = { name: "get_integration_resource_kind_details", description: "Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type.", @@ -67,7 +71,9 @@ const GetIntegrationResourcesInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetIntegrationResourcesTool: Tool = { +export const GetIntegrationResourcesTool: Tool< + typeof GetIntegrationResourcesInput +> = { name: "get_integration_resources", description: "List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration.", @@ -83,7 +89,9 @@ const GetIntegrationResourceByIdInput = z.object({ ), }); -export const GetIntegrationResourceByIdTool: Tool = { +export const GetIntegrationResourceByIdTool: Tool< + typeof GetIntegrationResourceByIdInput +> = { name: "get_integration_resource_by_id", description: "Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration.", @@ -150,7 +158,10 @@ export async function getIntegrationById( export async function getIntegrationResourceKinds( args: z.infer, ): Promise { - const url = new URL(`/v1/integrations/${args.integrationId}/resource-kinds`, baseApiUrl()); + const url = new URL( + `/v1/integrations/${args.integrationId}/resource-kinds`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -182,7 +193,10 @@ export async function getIntegrationResourceKinds( export async function getIntegrationResourceKindDetails( args: z.infer, ): Promise { - const url = new URL(`/v1/integrations/${args.integrationId}/resource-kinds/${args.resourceKind}`, baseApiUrl()); + const url = new URL( + `/v1/integrations/${args.integrationId}/resource-kinds/${args.resourceKind}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -207,7 +221,10 @@ export async function getIntegrationResourceKindDetails( export async function getIntegrationResources( args: z.infer, ): Promise { - const url = new URL(`/v1/integrations/${args.integrationId}/resources`, baseApiUrl()); + const url = new URL( + `/v1/integrations/${args.integrationId}/resources`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -239,7 +256,10 @@ export async function getIntegrationResources( export async function getIntegrationResourceById( args: z.infer, ): Promise { - const url = new URL(`/v1/integrations/${args.integrationId}/resources/${args.resourceId}`, baseApiUrl()); + const url = new URL( + `/v1/integrations/${args.integrationId}/resources/${args.resourceId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts index 0b3ba38..a9295cb 100644 --- a/src/operations/monitored-computers.ts +++ b/src/operations/monitored-computers.ts @@ -13,7 +13,9 @@ const GetMonitoredComputersInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetMonitoredComputersTool: Tool = { +export const GetMonitoredComputersTool: Tool< + typeof GetMonitoredComputersInput +> = { name: "get_monitored_computers", description: "List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization.", @@ -28,7 +30,9 @@ const GetMonitoredComputerByIdInput = z.object({ ), }); -export const GetMonitoredComputerByIdTool: Tool = { +export const GetMonitoredComputerByIdTool: Tool< + typeof GetMonitoredComputerByIdInput +> = { name: "get_monitored_computer_by_id", description: "Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information.", @@ -70,7 +74,10 @@ export async function getMonitoredComputers( export async function getMonitoredComputerById( args: z.infer, ): Promise { - const url = new URL(`/v1/monitored-computers/${args.computerId}`, baseApiUrl()); + const url = new URL( + `/v1/monitored-computers/${args.computerId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts index 294eb3a..0f533df 100644 --- a/src/operations/trust-centers.ts +++ b/src/operations/trust-centers.ts @@ -26,7 +26,9 @@ const GetTrustCenterAccessRequestsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetTrustCenterAccessRequestsTool: Tool = { +export const GetTrustCenterAccessRequestsTool: Tool< + typeof GetTrustCenterAccessRequestsInput +> = { name: "get_trust_center_access_requests", description: "List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information.", @@ -42,7 +44,9 @@ const GetTrustCenterAccessRequestInput = z.object({ ), }); -export const GetTrustCenterAccessRequestTool: Tool = { +export const GetTrustCenterAccessRequestTool: Tool< + typeof GetTrustCenterAccessRequestInput +> = { name: "get_trust_center_access_request", description: "Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions.", @@ -55,7 +59,9 @@ const GetTrustCenterViewerActivityEventsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetTrustCenterViewerActivityEventsTool: Tool = { +export const GetTrustCenterViewerActivityEventsTool: Tool< + typeof GetTrustCenterViewerActivityEventsInput +> = { name: "get_trust_center_viewer_activity_events", description: "List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics.", @@ -68,7 +74,9 @@ const GetTrustCenterControlCategoriesInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetTrustCenterControlCategoriesTool: Tool = { +export const GetTrustCenterControlCategoriesTool: Tool< + typeof GetTrustCenterControlCategoriesInput +> = { name: "get_trust_center_control_categories", description: "List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors.", @@ -84,7 +92,9 @@ const GetTrustCenterControlCategoryInput = z.object({ ), }); -export const GetTrustCenterControlCategoryTool: Tool = { +export const GetTrustCenterControlCategoryTool: Tool< + typeof GetTrustCenterControlCategoryInput +> = { name: "get_trust_center_control_category", description: "Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management.", @@ -97,7 +107,9 @@ const GetTrustCenterControlsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetTrustCenterControlsTool: Tool = { +export const GetTrustCenterControlsTool: Tool< + typeof GetTrustCenterControlsInput +> = { name: "get_trust_center_controls", description: "List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors.", @@ -113,7 +125,9 @@ const GetTrustCenterControlInput = z.object({ ), }); -export const GetTrustCenterControlTool: Tool = { +export const GetTrustCenterControlTool: Tool< + typeof GetTrustCenterControlInput +> = { name: "get_trust_center_control", description: "Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency.", @@ -137,9 +151,7 @@ const GetTrustCenterFaqInput = z.object({ slugId: z.string().describe(SLUG_ID_DESCRIPTION), faqId: z .string() - .describe( - "FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier", - ), + .describe("FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier"), }); export const GetTrustCenterFaqTool: Tool = { @@ -155,7 +167,9 @@ const GetTrustCenterResourcesInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetTrustCenterResourcesTool: Tool = { +export const GetTrustCenterResourcesTool: Tool< + typeof GetTrustCenterResourcesInput +> = { name: "get_trust_center_resources", description: "List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors.", @@ -171,7 +185,9 @@ const GetTrustCenterDocumentInput = z.object({ ), }); -export const GetTrustCenterDocumentTool: Tool = { +export const GetTrustCenterDocumentTool: Tool< + typeof GetTrustCenterDocumentInput +> = { name: "get_trust_center_document", description: "Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management.", @@ -207,7 +223,10 @@ export async function getTrustCenter( export async function getTrustCenterAccessRequests( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/access-requests`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/access-requests`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -239,7 +258,10 @@ export async function getTrustCenterAccessRequests( export async function getTrustCenterAccessRequest( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/access-requests/${args.accessRequestId}`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/access-requests/${args.accessRequestId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -264,7 +286,10 @@ export async function getTrustCenterAccessRequest( export async function getTrustCenterViewerActivityEvents( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/viewer-activity-events`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/viewer-activity-events`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -296,7 +321,10 @@ export async function getTrustCenterViewerActivityEvents( export async function getTrustCenterControlCategories( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/control-categories`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/control-categories`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -328,7 +356,10 @@ export async function getTrustCenterControlCategories( export async function getTrustCenterControlCategory( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/control-categories/${args.controlCategoryId}`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/control-categories/${args.controlCategoryId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -353,7 +384,10 @@ export async function getTrustCenterControlCategory( export async function getTrustCenterControls( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/controls`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/controls`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -385,7 +419,10 @@ export async function getTrustCenterControls( export async function getTrustCenterControl( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/controls/${args.trustCenterControlId}`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/controls/${args.trustCenterControlId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -442,7 +479,10 @@ export async function getTrustCenterFaqs( export async function getTrustCenterFaq( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/faqs/${args.faqId}`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/faqs/${args.faqId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -467,7 +507,10 @@ export async function getTrustCenterFaq( export async function getTrustCenterResources( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/resources`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/resources`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -499,7 +542,10 @@ export async function getTrustCenterResources( export async function getTrustCenterDocument( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/documents/${args.trustCenterDocumentId}`, baseApiUrl()); + const url = new URL( + `/v1/trust-centers/${args.slugId}/documents/${args.trustCenterDocumentId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); diff --git a/src/operations/vendor-risk-attributes.ts b/src/operations/vendor-risk-attributes.ts index 198416f..3034f12 100644 --- a/src/operations/vendor-risk-attributes.ts +++ b/src/operations/vendor-risk-attributes.ts @@ -13,7 +13,9 @@ const GetVendorRiskAttributesInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorRiskAttributesTool: Tool = { +export const GetVendorRiskAttributesTool: Tool< + typeof GetVendorRiskAttributesInput +> = { name: "get_vendor_risk_attributes", description: "List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization.", diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index b260582..1944546 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -64,7 +64,9 @@ const GetVendorSecurityReviewsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorSecurityReviewsTool: Tool = { +export const GetVendorSecurityReviewsTool: Tool< + typeof GetVendorSecurityReviewsInput +> = { name: "get_vendor_security_reviews", description: "Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities.", @@ -80,7 +82,9 @@ const GetVendorSecurityReviewByIdInput = z.object({ ), }); -export const GetVendorSecurityReviewByIdTool: Tool = { +export const GetVendorSecurityReviewByIdTool: Tool< + typeof GetVendorSecurityReviewByIdInput +> = { name: "get_vendor_security_review_by_id", description: "Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations.", @@ -98,7 +102,9 @@ const GetVendorSecurityReviewDocumentsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorSecurityReviewDocumentsTool: Tool = { +export const GetVendorSecurityReviewDocumentsTool: Tool< + typeof GetVendorSecurityReviewDocumentsInput +> = { name: "get_vendor_security_review_documents", description: "Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment.", @@ -229,7 +235,10 @@ export async function getVendorFindings( export async function getVendorSecurityReviews( args: z.infer, ): Promise { - const url = new URL(`/v1/vendors/${args.vendorId}/security-reviews`, baseApiUrl()); + const url = new URL( + `/v1/vendors/${args.vendorId}/security-reviews`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); @@ -261,7 +270,10 @@ export async function getVendorSecurityReviews( export async function getVendorSecurityReviewById( args: z.infer, ): Promise { - const url = new URL(`/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}`, baseApiUrl()); + const url = new URL( + `/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); @@ -286,7 +298,10 @@ export async function getVendorSecurityReviewById( export async function getVendorSecurityReviewDocuments( args: z.infer, ): Promise { - const url = new URL(`/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}/documents`, baseApiUrl()); + const url = new URL( + `/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}/documents`, + baseApiUrl(), + ); if (args.pageSize !== undefined) { url.searchParams.append("pageSize", args.pageSize.toString()); diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index 4593f00..dbde203 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -28,12 +28,13 @@ const GetVulnerabilityByIdInput = z.object({ ), }); -export const GetVulnerabilityByIdTool: Tool = { - name: "get_vulnerability_by_id", - description: - "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from get_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status.", - parameters: GetVulnerabilityByIdInput, -}; +export const GetVulnerabilityByIdTool: Tool = + { + name: "get_vulnerability_by_id", + description: + "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from get_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status.", + parameters: GetVulnerabilityByIdInput, + }; export async function getVulnerabilities( args: z.infer, @@ -70,7 +71,10 @@ export async function getVulnerabilities( export async function getVulnerabilityById( args: z.infer, ): Promise { - const url = new URL(`/v1/vulnerabilities/${args.vulnerabilityId}`, baseApiUrl()); + const url = new URL( + `/v1/vulnerabilities/${args.vulnerabilityId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); diff --git a/src/operations/vulnerability-remediations.ts b/src/operations/vulnerability-remediations.ts index bf01622..86d9ed9 100644 --- a/src/operations/vulnerability-remediations.ts +++ b/src/operations/vulnerability-remediations.ts @@ -13,7 +13,9 @@ const GetVulnerabilityRemediationsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVulnerabilityRemediationsTool: Tool = { +export const GetVulnerabilityRemediationsTool: Tool< + typeof GetVulnerabilityRemediationsInput +> = { name: "get_vulnerability_remediations", description: "List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues.", diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts index d0df665..9c7161e 100644 --- a/src/operations/vulnerable-assets.ts +++ b/src/operations/vulnerable-assets.ts @@ -28,7 +28,9 @@ const GetVulnerableAssetByIdInput = z.object({ ), }); -export const GetVulnerableAssetByIdTool: Tool = { +export const GetVulnerableAssetByIdTool: Tool< + typeof GetVulnerableAssetByIdInput +> = { name: "get_vulnerable_asset_by_id", description: "Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status.", @@ -70,7 +72,10 @@ export async function getVulnerableAssets( export async function getVulnerableAssetById( args: z.infer, ): Promise { - const url = new URL(`/v1/vulnerable-assets/${args.vulnerableAssetId}`, baseApiUrl()); + const url = new URL( + `/v1/vulnerable-assets/${args.vulnerableAssetId}`, + baseApiUrl(), + ); const response = await makeAuthenticatedRequest(url.toString()); From 32867e4c38d2512bd7ea1cf2138c5174993b279a Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Wed, 24 Sep 2025 12:00:04 -0400 Subject: [PATCH 16/24] Refactor tool names and descriptions for clarity - get_* -> list_* for endpoints that return a list of items - get_* -> get_* for endpoints that return a single item --- README.md | 379 +++++++++---- src/eval/README.md | 32 +- src/eval/eval.ts | 80 +-- src/index.ts | 564 +++++++++---------- src/operations/controls.ts | 64 +-- src/operations/discovered-vendors.ts | 26 +- src/operations/documents.ts | 60 +- src/operations/frameworks.ts | 40 +- src/operations/groups.ts | 36 +- src/operations/integrations.ts | 64 +-- src/operations/monitored-computers.ts | 28 +- src/operations/people.ts | 24 +- src/operations/policies.ts | 24 +- src/operations/risks.ts | 26 +- src/operations/tests.ts | 40 +- src/operations/vendor-risk-attributes.ts | 14 +- src/operations/vendors.ts | 90 +-- src/operations/vulnerabilities.ts | 26 +- src/operations/vulnerability-remediations.ts | 14 +- src/operations/vulnerable-assets.ts | 26 +- 20 files changed, 893 insertions(+), 764 deletions(-) diff --git a/README.md b/README.md index f491e5f..8ef9595 100644 --- a/README.md +++ b/README.md @@ -6,33 +6,79 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid ## Features -### Security Test Management +### Controls -- Access Vanta's 1,200+ automated security tests that run continuously to monitor compliance -- Retrieve test results with filtering by status (passing/failing), cloud provider (AWS/Azure/GCP), or compliance framework -- Get detailed information about failing resources (test entities) that need remediation +- List all security controls across all frameworks in your Vanta account +- View control names, descriptions, framework mappings, and implementation status +- Get specific tests that validate each security control +- Access pre-built controls from Vanta's control library +- View documents providing evidence for specific security controls +- Understand which automated tests monitor compliance for specific controls -### Compliance Framework Operations +| Tool Name | Description | +| --------- | ----------- | +| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Returns test details, current status, and any failing entities for the control's tests. | +| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. | +| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. | -- Access 35+ supported compliance frameworks including SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, and PCI -- Retrieve detailed control requirements and evidence mappings for each framework -- Monitor framework completion progress and compliance status -- Get specific control details that map to automated tests and required documentation +### Discovered Vendors -### Security Control Management +- List vendors automatically discovered through integrations for potential vendor onboarding +- Access detailed account information for discovered vendors including integration sources +- Understand vendor relationships and account structures before converting to managed vendors +- Streamline vendor risk assessment workflows by identifying unmanaged vendor relationships -- List all security controls across all compliance frameworks in your account -- View control names, descriptions, framework mappings, and implementation status -- Get specific tests that validate each security control -- Understand which automated tests monitor compliance for specific controls +| Tool Name | Description | +| --------- | ----------- | +| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. | +| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. | + +### Documents + +- List all documents in your Vanta account for compliance and evidence management +- Get detailed information about specific documents including metadata and compliance mappings +- View security controls that are mapped to or associated with documents as evidence +- Access external links and references associated with documents +- List all files and uploads attached to documents for compliance documentation +- Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata + +| Tool Name | Description | +| --------- | ----------- | +| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. | +| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. | +| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. | +| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. | +| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. | +| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload with automatic MIME type handling. | -### Risk Scenario Management +### Frameworks -- Get all the risk scenarios you are managing in your current risk register. -- Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. -- Filterable by risk category (Access Control, Cryptography, Privacy, and many others). +- List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, etc.) +- View completion status and progress metrics for each framework +- Get detailed security control requirements for specific compliance frameworks +- Access implementation guidance and current compliance status for framework controls + +| Tool Name | Description | +| --------- | ----------- | +| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. | +| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. | +| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. | + +### Groups + +- List all organizational groups for structure and access management +- Get detailed group information including member counts and access permissions +- View group membership to understand who has group-based access permissions -### Integration Management +| Tool Name | Description | +| --------- | ----------- | +| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. | +| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. | +| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. | + +### Integrations - List all connected integrations in your Vanta account (AWS, Azure, GCP, Snyk, etc.) - Get detailed information about specific integrations and their configurations @@ -43,67 +89,74 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all infrastructure resources discovered by integrations - Access detailed resource information including metadata, compliance status, and configuration -### Vendor Management +| Tool Name | Description | +| --------- | ----------- | +| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist. | +| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. | +| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. | +| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. | +| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. | +| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. | -- List all vendors in your Vanta account for vendor risk management -- Get detailed vendor information including contact details and website URLs -- Access vendor risk assessment status and compliance information -- Manage vendor relationships and due diligence tracking -- View all documents associated with vendors for compliance purposes -- Access security findings and risk assessment results for vendors -- Review history of security assessments and due diligence activities -- Get detailed information about specific vendor security reviews -- Access supporting documentation and reports for security assessments +### Monitored Computers -### Document Management +- Monitor all computers across your organization for compliance and security +- Access detailed computer information including hostnames, operating systems, and security status +- Manage endpoint security and compliance across diverse computing environments -- List all documents in your Vanta account for compliance and evidence management -- Get detailed information about specific documents including metadata and compliance mappings -- View security controls that are mapped to or associated with documents as evidence -- Access external links and references associated with documents -- List all files and uploads attached to documents for compliance documentation -- Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata +| Tool Name | Description | +| --------- | ----------- | +| [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. | +| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. | -### Policy Management +### People + +- List all people in your organization for compliance and security management +- Access detailed person information including roles, email addresses, and group memberships +- Manage organizational structure and access control through comprehensive people data + +| Tool Name | Description | +| --------- | ----------- | +| [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. | +| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. | + +### Policies - List all policies in your Vanta account for compliance and governance management - Get detailed policy information including content, approval status, and compliance mappings - Access organizational policies for security, privacy, and operational governance - View policy metadata including names, types, and associated compliance frameworks -### Discovered Vendor Management - -- List vendors automatically discovered through integrations for potential vendor onboarding -- Access detailed account information for discovered vendors including integration sources -- Understand vendor relationships and account structures before converting to managed vendors -- Streamline vendor risk assessment workflows by identifying unmanaged vendor relationships +| Tool Name | Description | +| --------- | ----------- | +| [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. | +| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. | -### Group & People Management +### Risks -- List all organizational groups for structure and access management -- Get detailed group information including member counts and access permissions -- View group membership to understand who has group-based access permissions -- List all people in your organization for compliance and security management -- Access detailed person information including roles, email addresses, and group memberships -- Manage organizational structure and access control through comprehensive people and group data +- Get all the risk scenarios you are managing in your current risk register +- Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more +- Filterable by risk category (Access Control, Cryptography, Privacy, and many others) -### Vulnerability Management +| Tool Name | Description | +| --------- | ----------- | +| [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. | +| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. | -- Monitor all vulnerabilities detected across your infrastructure and applications -- Access detailed vulnerability information including CVE data, severity levels, and affected assets -- Track vulnerability remediation efforts and timelines for security management -- Identify vulnerable assets and understand their security status -- Prioritize security efforts based on asset vulnerability associations and risk levels +### Tests -### Endpoint & Risk Management +- Access Vanta's 1,200+ automated security tests that run continuously to monitor compliance +- Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration, or compliance framework +- Get specific resources (entities) that are failing particular security tests +- Essential for understanding exactly which infrastructure components need remediation -- Monitor all computers across your organization for compliance and security -- Access detailed computer information including hostnames, operating systems, and security status -- Manage endpoint security and compliance across diverse computing environments -- Understand available vendor risk attributes for comprehensive risk assessment -- Categorize and evaluate vendor risks using standardized risk assessment criteria +| Tool Name | Description | +| --------- | ----------- | +| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status, cloud integration, or compliance framework. Returns test results showing which security controls are passing or failing. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. Essential for understanding exactly which infrastructure components need remediation. | +| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the list_tests response or from the address bar of your browser. | -### Trust Center Management +### Trust Centers - Access complete Trust Center configuration, branding, and public visibility settings - Manage Trust Center access requests from potential customers and stakeholders @@ -114,6 +167,82 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Provide downloadable resources including compliance documents and certifications - Enable customer self-service access to compliance and security information +| Tool Name | Description | +| --------- | ----------- | +| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | +| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | +| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | +| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | +| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | +| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | +| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | +| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | +| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | +| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | +| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | +| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | + +### Vendor Risk Attributes + +- Understand available vendor risk attributes for comprehensive risk assessment +- Categorize and evaluate vendor risks using standardized risk assessment criteria +- Access risk attribute IDs, names, categories, and assessment criteria for vendor risk management + +| Tool Name | Description | +| --------- | ----------- | +| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. | + +### Vendors + +- List all vendors in your Vanta account for vendor risk management +- Get detailed vendor information including contact details and website URLs +- Access vendor risk assessment status and compliance information +- Manage vendor relationships and due diligence tracking +- View all documents associated with vendors for compliance purposes +- Access security findings and risk assessment results for vendors +- Review history of security assessments and due diligence activities +- Get detailed information about specific vendor security reviews +- Access supporting documentation and reports for security assessments + +| Tool Name | Description | +| --------- | ----------- | +| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. | +| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. | +| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. | +| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. | +| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. | +| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. | +| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. | + +### Vulnerabilities + +- Monitor all vulnerabilities detected across your infrastructure and applications +- Access detailed vulnerability information including CVE data, severity levels, and affected assets + +| Tool Name | Description | +| --------- | ----------- | +| [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. | +| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. | + +### Vulnerability Remediations + +- Track vulnerability remediation efforts and timelines for security management +- Ensure timely resolution of security issues through comprehensive remediation tracking + +| Tool Name | Description | +| --------- | ----------- | +| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. | + +### Vulnerable Assets + +- Identify vulnerable assets and understand their security status +- Prioritize security efforts based on asset vulnerability associations and risk levels + +| Tool Name | Description | +| --------- | ----------- | +| [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. | +| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. | + ### Multi-Region Support - US, EU, and AUS regions with region-specific API endpoints @@ -123,67 +252,67 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `get_tests` | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | -| `get_test_entities` | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | -| `get_test_by_id` | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `get_tests` response or from the address bar of your browser after /tests/. | -| `get_frameworks` | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | -| `get_framework_controls` | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | -| `get_framework_by_id` | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from get_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | -| `get_controls` | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | -| `get_control_tests` | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | -| `get_library_controls` | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from get_controls which lists controls already in your account - this shows available controls you can implement. | -| `get_control_documents` | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | -| `get_control_by_id` | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from get_controls or get_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | -| `get_risks` | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | -| `get_risk_by_id` | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from get_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | -| `get_integrations` | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | -| `get_integration_by_id` | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from get_integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | -| `get_integration_resource_kinds` | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | -| `get_integration_resource_kind_details` | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | -| `get_integration_resources` | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | -| `get_integration_resource_by_id` | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | -| `get_vendors` | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | -| `get_vendor_by_id` | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from get_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | -| `get_vendor_documents` | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | -| `get_vendor_findings` | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | -| `get_vendor_security_reviews` | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | -| `get_vendor_security_review_by_id` | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | -| `get_vendor_security_review_documents` | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | -| `get_documents` | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | -| `get_document_by_id` | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from get_documents response. Returns complete document details including name, type, metadata, and compliance mappings. | -| `get_document_controls` | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | -| `get_document_links` | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | -| `get_document_uploads` | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | -| `download_document_file` | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | -| `get_policies` | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | -| `get_policy_by_id` | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | -| `get_discovered_vendors` | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | -| `get_discovered_vendor_accounts` | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | -| `get_groups` | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | -| `get_group_by_id` | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from get_groups response. Returns complete group details including name, description, member count, and access permissions. | -| `get_group_people` | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | -| `get_people` | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | -| `get_person_by_id` | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from get_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | -| `get_vulnerabilities` | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | -| `get_vulnerability_by_id` | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from get_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | -| `get_vulnerability_remediations` | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | -| `get_vulnerable_assets` | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | -| `get_vulnerable_asset_by_id` | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | -| `get_monitored_computers` | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | -| `get_monitored_computer_by_id` | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | -| `get_vendor_risk_attributes` | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | -| `get_trust_center` | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | -| `get_trust_center_access_requests` | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | -| `get_trust_center_access_request` | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | -| `get_trust_center_viewer_activity_events` | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | -| `get_trust_center_control_categories` | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | -| `get_trust_center_control_category` | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | -| `get_trust_center_controls` | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | -| `get_trust_center_control` | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | -| `get_trust_center_faqs` | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | -| `get_trust_center_faq` | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | -| `get_trust_center_resources` | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | -| `get_trust_center_document` | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | +| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | +| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | +| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | +| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | +| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | +| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | +| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from list_controls which lists controls already in your account - this shows available controls you can implement. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | +| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from list_controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | +| [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | +| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from list_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | +| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | +| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from list_integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | +| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | +| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | +| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | +| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | +| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | +| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from list_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | +| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | +| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | +| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | +| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | +| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | +| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | +| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from list_documents response. Returns complete document details including name, type, metadata, and compliance mappings. | +| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | +| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | +| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | +| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | +| [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | +| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from list_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | +| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | +| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | +| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | +| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from list_groups response. Returns complete group details including name, description, member count, and access permissions. | +| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | +| [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | +| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from list_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | +| [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | +| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | +| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | +| [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | +| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from list_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | +| [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | +| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from list_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | +| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | +| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | +| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | +| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | +| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | +| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | +| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | +| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | +| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | +| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | +| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | +| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | +| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | ## Configuration @@ -314,7 +443,7 @@ The inspector will open in your browser, allowing you to test tool calls and ins ```typescript { - "tool": "get_tests", + "tool": "list_tests", "arguments": { "statusFilter": "NEEDS_ATTENTION", "integrationFilter": "aws", diff --git a/src/eval/README.md b/src/eval/README.md index cebf6c6..6fffaf7 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -44,19 +44,19 @@ The evaluation includes 54 test cases covering: ### ✅ **Tool Selection Tests** -- **AWS Security Review**: `get_tests` with AWS and NEEDS_ATTENTION filters -- **SOC2 Compliance**: `get_tests` with SOC2 framework filter -- **Entity Details**: `get_test_entities` for specific failing resources -- **Framework Listing**: `get_frameworks` for available frameworks -- **Control Requirements**: `get_framework_controls` for specific framework details -- **Status Percentage**: `get_frameworks` for completion percentages -- **Control Listing**: `get_controls` for all security controls -- **Control Tests**: `get_control_tests` for tests validating specific controls -- **Library Controls**: `get_library_controls` for available Vanta library controls -- **Control Documents**: `get_control_documents` for documents associated with controls -- **Control Details**: `get_control_by_id` for specific control information -- **Framework Details**: `get_framework_by_id` for specific framework information -- **Risk Details**: `get_risk_by_id` for specific risk scenario information +- **AWS Security Review**: `list_tests` with AWS and NEEDS_ATTENTION filters +- **SOC2 Compliance**: `list_tests` with SOC2 framework filter +- **Entity Details**: `list_test_entities` for specific failing resources +- **Framework Listing**: `list_frameworks` for available frameworks +- **Control Requirements**: `list_framework_controls` for specific framework details +- **Status Percentage**: `list_frameworks` for completion percentages +- **Control Listing**: `list_controls` for all security controls +- **Control Tests**: `list_control_tests` for tests validating specific controls +- **Library Controls**: `list_library_controls` for available Vanta library controls +- **Control Documents**: `list_control_documents` for documents associated with controls +- **Control Details**: `get_control` for specific control information +- **Framework Details**: `get_framework` for specific framework information +- **Risk Details**: `get_risk` for specific risk scenario information - **Integration Listing**: `get_integrations` for connected integrations - **Integration Details**: `get_integration_by_id` for specific integration information - **Vendor Listing**: `get_vendors` for all vendors @@ -108,10 +108,10 @@ The evaluation includes 54 test cases covering: 🧪 Vanta MCP Server Tool Evaluation ==================================== -📝 Test: Should call get_tests with AWS filter and NEEDS_ATTENTION status +📝 Test: Should call list_tests with AWS filter and NEEDS_ATTENTION status 💬 Prompt: "What security issues do I have in my AWS infrastructure?" -🎯 Expected Tool: get_tests -✅ PASS: Correctly called get_tests +🎯 Expected Tool: list_tests +✅ PASS: Correctly called list_tests ✅ Parameters match expected values 📋 Called with: { "statusFilter": "NEEDS_ATTENTION", diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 15a2df8..4ec14eb 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -494,7 +494,7 @@ interface TestCase { const testCases: TestCase[] = [ { prompt: "What security issues do I have in my AWS infrastructure?", - expectedTool: "get_tests", + expectedTool: "list_tests", expectedParams: { statusFilter: "NEEDS_ATTENTION", integrationFilter: "aws", @@ -504,7 +504,7 @@ const testCases: TestCase[] = [ }, { prompt: "Show me all my SOC2 compliance tests that are failing", - expectedTool: "get_tests", + expectedTool: "list_tests", expectedParams: { frameworkFilter: "soc2", statusFilter: "NEEDS_ATTENTION", @@ -514,122 +514,122 @@ const testCases: TestCase[] = [ { prompt: "Show me the specific failing entities for test ID aws-security-groups-open-to-world", - expectedTool: "get_test_entities", + expectedTool: "list_test_entities", expectedParams: { testId: "aws-security-groups-open-to-world" }, description: "Should call get_test_entities for specific test details", }, { prompt: "Show me the details of test ID aws-security-groups-open-to-world", - expectedTool: "get_test_by_id", + expectedTool: "get_test", expectedParams: { testId: "aws-security-groups-open-to-world" }, description: "Should call get_test_by_id for specific test details", }, { prompt: "What compliance frameworks are we tracking?", - expectedTool: "get_frameworks", + expectedTool: "list_frameworks", expectedParams: {}, description: "Should call get_frameworks to list available frameworks", }, { prompt: "Get the control requirements for framework ID soc2", - expectedTool: "get_framework_controls", + expectedTool: "list_framework_controls", expectedParams: { frameworkId: "soc2" }, description: "Should call get_framework_controls for SOC2", }, { prompt: "What is the current % status of my SOC 2?", - expectedTool: "get_frameworks", + expectedTool: "list_frameworks", expectedParams: {}, description: "Should call get_frameworks to get SOC2 completion percentage", }, { prompt: "List all security controls in my Vanta account", - expectedTool: "get_controls", + expectedTool: "list_controls", expectedParams: {}, description: "Should call get_controls to list all available controls", }, { prompt: "Show me the tests for control ID access-control-1", - expectedTool: "get_control_tests", + expectedTool: "list_control_tests", expectedParams: { controlId: "access-control-1" }, description: "Should call get_control_tests for specific control", }, { prompt: "What controls are available in the Vanta library that I can add?", - expectedTool: "get_library_controls", + expectedTool: "list_library_controls", expectedParams: {}, description: "Should call get_library_controls to list available library controls", }, { prompt: "Show me the documents for control ID access-control-1", - expectedTool: "get_control_documents", + expectedTool: "list_control_documents", expectedParams: { controlId: "access-control-1" }, description: "Should call get_control_documents for specific control", }, { prompt: "Get details for control ID data-protection-2", - expectedTool: "get_control_by_id", + expectedTool: "get_control", expectedParams: { controlId: "data-protection-2" }, description: "Should call get_control_by_id for specific control details", }, { prompt: "Show me details for framework ID soc2", - expectedTool: "get_framework_by_id", + expectedTool: "get_framework", expectedParams: { frameworkId: "soc2" }, description: "Should call get_framework_by_id for specific framework details", }, { prompt: "Get details for risk scenario ID risk-scenario-123", - expectedTool: "get_risk_by_id", + expectedTool: "get_risk", expectedParams: { riskId: "risk-scenario-123" }, description: "Should call get_risk_by_id for specific risk scenario details", }, { prompt: "What integrations are connected to my Vanta account?", - expectedTool: "get_integrations", + expectedTool: "list_integrations", expectedParams: {}, description: "Should call get_integrations to list all connected integrations", }, { prompt: "Show me details for integration ID aws", - expectedTool: "get_integration_by_id", + expectedTool: "get_integration", expectedParams: { integrationId: "aws" }, description: "Should call get_integration_by_id for specific integration details", }, { prompt: "List all vendors in my Vanta account", - expectedTool: "get_vendors", + expectedTool: "list_vendors", expectedParams: {}, description: "Should call get_vendors to list all vendors", }, { prompt: "Get details for vendor ID vendor-123", - expectedTool: "get_vendor_by_id", + expectedTool: "get_vendor", expectedParams: { vendorId: "vendor-123" }, description: "Should call get_vendor_by_id for specific vendor details", }, { prompt: "Show me all the documents we have uploaded to Vanta for compliance purposes.", - expectedTool: "get_documents", + expectedTool: "list_documents", expectedParams: {}, description: "Should call get_documents to list all compliance documents", }, { prompt: "I need to see the details of document DOC-12345 including its metadata and compliance mappings.", - expectedTool: "get_document_by_id", + expectedTool: "get_document", expectedParams: { documentId: "DOC-12345" }, description: "Should call get_document_by_id for specific document details", }, { prompt: "Which security controls are mapped to document DOC-789?", - expectedTool: "get_document_controls", + expectedTool: "list_document_controls", expectedParams: { documentId: "DOC-789" }, description: "Should call get_document_controls to find controls associated with document", @@ -637,14 +637,14 @@ const testCases: TestCase[] = [ { prompt: "What external links and references are attached to document POLICY-456?", - expectedTool: "get_document_links", + expectedTool: "list_document_links", expectedParams: { documentId: "POLICY-456" }, description: "Should call get_document_links to get external references for document", }, { prompt: "List all the files uploaded to document SEC-123.", - expectedTool: "get_document_uploads", + expectedTool: "list_document_uploads", expectedParams: { documentId: "SEC-123" }, description: "Should call get_document_uploads to list file uploads for document", @@ -660,21 +660,21 @@ const testCases: TestCase[] = [ { prompt: "Show me all the policies we have established for our organization.", - expectedTool: "get_policies", + expectedTool: "list_policies", expectedParams: {}, description: "Should call get_policies to list all organizational policies", }, { prompt: "I need to review the details of our data retention policy with ID POLICY-789.", - expectedTool: "get_policy_by_id", + expectedTool: "get_policy", expectedParams: { policyId: "POLICY-789" }, description: "Should call get_policy_by_id for specific policy details", }, { prompt: "Show me all the vendors that have been discovered through our integrations but aren't yet managed.", - expectedTool: "get_discovered_vendors", + expectedTool: "list_discovered_vendors", expectedParams: {}, description: "Should call get_discovered_vendors to list automatically discovered vendors", @@ -682,7 +682,7 @@ const testCases: TestCase[] = [ { prompt: "I need detailed account information for all discovered vendor accounts from our integrations.", - expectedTool: "get_discovered_vendor_accounts", + expectedTool: "list_discovered_vendor_accounts", expectedParams: {}, description: "Should call get_discovered_vendor_accounts to get detailed vendor account information", @@ -690,40 +690,40 @@ const testCases: TestCase[] = [ { prompt: "Show me all the organizational groups we have set up for access management.", - expectedTool: "get_groups", + expectedTool: "list_groups", expectedParams: {}, description: "Should call get_groups to list all organizational groups", }, { prompt: "I need details about the Engineering group with ID GROUP-456.", - expectedTool: "get_group_by_id", + expectedTool: "get_group", expectedParams: { groupId: "GROUP-456" }, description: "Should call get_group_by_id for specific group details", }, { prompt: "Who are all the members of the Security team group?", - expectedTool: "get_group_people", + expectedTool: "list_group_people", expectedParams: { groupId: "Security team" }, description: "Should call get_group_people to list people in a specific group", }, { prompt: "List all people in our organization for the compliance audit.", - expectedTool: "get_people", + expectedTool: "list_people", expectedParams: {}, description: "Should call get_people to list all people in the organization", }, { prompt: "Get me the details for employee PERSON-789.", - expectedTool: "get_person_by_id", + expectedTool: "get_person", expectedParams: { personId: "PERSON-789" }, description: "Should call get_person_by_id for specific person details", }, { prompt: "Show me all the security vulnerabilities detected in our infrastructure.", - expectedTool: "get_vulnerabilities", + expectedTool: "list_vulnerabilities", expectedParams: {}, description: "Should call get_vulnerabilities to list all detected vulnerabilities", @@ -731,14 +731,14 @@ const testCases: TestCase[] = [ { prompt: "I need detailed information about vulnerability VULN-456 including its CVE data.", - expectedTool: "get_vulnerability_by_id", + expectedTool: "get_vulnerability", expectedParams: { vulnerabilityId: "VULN-456" }, description: "Should call get_vulnerability_by_id for specific vulnerability details", }, { prompt: "What vulnerability remediations are currently in progress?", - expectedTool: "get_vulnerability_remediations", + expectedTool: "list_vulnerability_remediations", expectedParams: {}, description: "Should call get_vulnerability_remediations to track remediation efforts", @@ -746,7 +746,7 @@ const testCases: TestCase[] = [ { prompt: "List all assets that are affected by vulnerabilities for our security review.", - expectedTool: "get_vulnerable_assets", + expectedTool: "list_vulnerable_assets", expectedParams: {}, description: "Should call get_vulnerable_assets to identify affected infrastructure", @@ -754,7 +754,7 @@ const testCases: TestCase[] = [ { prompt: "Get details about vulnerable asset ASSET-789 and its security status.", - expectedTool: "get_vulnerable_asset_by_id", + expectedTool: "get_vulnerable_asset", expectedParams: { vulnerableAssetId: "ASSET-789" }, description: "Should call get_vulnerable_asset_by_id for specific asset vulnerability details", @@ -762,14 +762,14 @@ const testCases: TestCase[] = [ { prompt: "Show me all the computers being monitored for compliance across our organization.", - expectedTool: "get_monitored_computers", + expectedTool: "list_monitored_computers", expectedParams: {}, description: "Should call get_monitored_computers to list all monitored computers", }, { prompt: "I need details about the monitored computer with ID COMP-456.", - expectedTool: "get_monitored_computer_by_id", + expectedTool: "get_monitored_computer", expectedParams: { computerId: "COMP-456" }, description: "Should call get_monitored_computer_by_id for specific computer details", @@ -777,7 +777,7 @@ const testCases: TestCase[] = [ { prompt: "What vendor risk attributes are available for evaluating our vendors?", - expectedTool: "get_vendor_risk_attributes", + expectedTool: "list_vendor_risk_attributes", expectedParams: {}, description: "Should call get_vendor_risk_attributes to list available risk assessment criteria", diff --git a/src/index.ts b/src/index.ts index 803f117..fc2c3a2 100644 --- a/src/index.ts +++ b/src/index.ts @@ -3,134 +3,134 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { - getTestEntities, - GetTestEntitiesTool, - getTests, - GetTestsTool, - getTestById, - GetTestByIdTool, + listTestEntities, + ListTestEntitiesTool, + listTests, + ListTestsTool, + getTest, + GetTestTool, } from "./operations/tests.js"; import { - GetFrameworkControlsTool, - GetFrameworksTool, - GetFrameworkByIdTool, - getFrameworkControls, - getFrameworks, - getFrameworkById, + ListFrameworkControlsTool, + ListFrameworksTool, + GetFrameworkTool, + listFrameworkControls, + listFrameworks, + getFramework, } from "./operations/frameworks.js"; import { - GetControlsTool, - GetControlTestsTool, - GetLibraryControlsTool, - GetControlDocumentsTool, - GetControlByIdTool, - getControls, - getControlTests, - getLibraryControls, - getControlDocuments, - getControlById, + ListControlsTool, + ListControlTestsTool, + ListLibraryControlsTool, + ListControlDocumentsTool, + GetControlTool, + listControls, + listControlTests, + listLibraryControls, + listControlDocuments, + getControl, } from "./operations/controls.js"; import { - getRisks, - GetRisksTool, - getRiskById, - GetRiskByIdTool, + listRisks, + ListRisksTool, + getRisk, + GetRiskTool, } from "./operations/risks.js"; import { - getIntegrations, - GetIntegrationsTool, - getIntegrationById, - GetIntegrationByIdTool, - getIntegrationResourceKinds, - GetIntegrationResourceKindsTool, + listIntegrations, + ListIntegrationsTool, + getIntegration, + GetIntegrationTool, + listIntegrationResourceKinds, + ListIntegrationResourceKindsTool, getIntegrationResourceKindDetails, GetIntegrationResourceKindDetailsTool, - getIntegrationResources, - GetIntegrationResourcesTool, - getIntegrationResourceById, - GetIntegrationResourceByIdTool, + listIntegrationResources, + ListIntegrationResourcesTool, + getIntegrationResource, + GetIntegrationResourceTool, } from "./operations/integrations.js"; import { - getVendors, - GetVendorsTool, - getVendorById, - GetVendorByIdTool, - getVendorDocuments, - GetVendorDocumentsTool, - getVendorFindings, - GetVendorFindingsTool, - getVendorSecurityReviews, - GetVendorSecurityReviewsTool, - getVendorSecurityReviewById, - GetVendorSecurityReviewByIdTool, - getVendorSecurityReviewDocuments, - GetVendorSecurityReviewDocumentsTool, + listVendors, + ListVendorsTool, + getVendor, + GetVendorTool, + listVendorDocuments, + ListVendorDocumentsTool, + listVendorFindings, + ListVendorFindingsTool, + listVendorSecurityReviews, + ListVendorSecurityReviewsTool, + getVendorSecurityReview, + GetVendorSecurityReviewTool, + listVendorSecurityReviewDocuments, + ListVendorSecurityReviewDocumentsTool, } from "./operations/vendors.js"; import { - getDocuments, - GetDocumentsTool, - getDocumentById, - GetDocumentByIdTool, - getDocumentControls, - GetDocumentControlsTool, - getDocumentLinks, - GetDocumentLinksTool, - getDocumentUploads, - GetDocumentUploadsTool, + listDocuments, + ListDocumentsTool, + getDocument, + GetDocumentTool, + listDocumentControls, + ListDocumentControlsTool, + listDocumentLinks, + ListDocumentLinksTool, + listDocumentUploads, + ListDocumentUploadsTool, downloadDocumentFile, DownloadDocumentFileTool, } from "./operations/documents.js"; import { - getPolicies, - GetPoliciesTool, - getPolicyById, - GetPolicyByIdTool, + listPolicies, + ListPoliciesTool, + getPolicy, + GetPolicyTool, } from "./operations/policies.js"; import { - getDiscoveredVendors, - GetDiscoveredVendorsTool, - getDiscoveredVendorAccounts, - GetDiscoveredVendorAccountsTool, + listDiscoveredVendors, + ListDiscoveredVendorsTool, + listDiscoveredVendorAccounts, + ListDiscoveredVendorAccountsTool, } from "./operations/discovered-vendors.js"; import { - getGroups, - GetGroupsTool, - getGroupById, - GetGroupByIdTool, - getGroupPeople, - GetGroupPeopleTool, + listGroups, + ListGroupsTool, + getGroup, + GetGroupTool, + listGroupPeople, + ListGroupPeopleTool, } from "./operations/groups.js"; import { - getPeople, - GetPeopleTool, - getPersonById, - GetPersonByIdTool, + listPeople, + ListPeopleTool, + getPerson, + GetPersonTool, } from "./operations/people.js"; import { - getVulnerabilities, - GetVulnerabilitiesTool, - getVulnerabilityById, - GetVulnerabilityByIdTool, + listVulnerabilities, + ListVulnerabilitiesTool, + getVulnerability, + GetVulnerabilityTool, } from "./operations/vulnerabilities.js"; import { - getVulnerabilityRemediations, - GetVulnerabilityRemediationsTool, + listVulnerabilityRemediations, + ListVulnerabilityRemediationsTool, } from "./operations/vulnerability-remediations.js"; import { - getVulnerableAssets, - GetVulnerableAssetsTool, - getVulnerableAssetById, - GetVulnerableAssetByIdTool, + listVulnerableAssets, + ListVulnerableAssetsTool, + getVulnerableAsset, + GetVulnerableAssetTool, } from "./operations/vulnerable-assets.js"; import { - getMonitoredComputers, - GetMonitoredComputersTool, - getMonitoredComputerById, - GetMonitoredComputerByIdTool, + listMonitoredComputers, + ListMonitoredComputersTool, + getMonitoredComputer, + GetMonitoredComputerTool, } from "./operations/monitored-computers.js"; import { - getVendorRiskAttributes, - GetVendorRiskAttributesTool, + listVendorRiskAttributes, + ListVendorRiskAttributesTool, } from "./operations/vendor-risk-attributes.js"; import { getTrustCenter, @@ -168,115 +168,115 @@ const server = new McpServer({ }); server.tool( - GetTestsTool.name, - GetTestsTool.description, - GetTestsTool.parameters.shape, - getTests, + ListTestsTool.name, + ListTestsTool.description, + ListTestsTool.parameters.shape, + listTests, ); server.tool( - GetTestByIdTool.name, - GetTestByIdTool.description, - GetTestByIdTool.parameters.shape, - getTestById, + GetTestTool.name, + GetTestTool.description, + GetTestTool.parameters.shape, + getTest, ); server.tool( - GetTestEntitiesTool.name, - GetTestEntitiesTool.description, - GetTestEntitiesTool.parameters.shape, - getTestEntities, + ListTestEntitiesTool.name, + ListTestEntitiesTool.description, + ListTestEntitiesTool.parameters.shape, + listTestEntities, ); server.tool( - GetFrameworksTool.name, - GetFrameworksTool.description, - GetFrameworksTool.parameters.shape, - getFrameworks, + ListFrameworksTool.name, + ListFrameworksTool.description, + ListFrameworksTool.parameters.shape, + listFrameworks, ); server.tool( - GetFrameworkControlsTool.name, - GetFrameworkControlsTool.description, - GetFrameworkControlsTool.parameters.shape, - getFrameworkControls, + ListFrameworkControlsTool.name, + ListFrameworkControlsTool.description, + ListFrameworkControlsTool.parameters.shape, + listFrameworkControls, ); server.tool( - GetFrameworkByIdTool.name, - GetFrameworkByIdTool.description, - GetFrameworkByIdTool.parameters.shape, - getFrameworkById, + GetFrameworkTool.name, + GetFrameworkTool.description, + GetFrameworkTool.parameters.shape, + getFramework, ); server.tool( - GetControlsTool.name, - GetControlsTool.description, - GetControlsTool.parameters.shape, - getControls, + ListControlsTool.name, + ListControlsTool.description, + ListControlsTool.parameters.shape, + listControls, ); server.tool( - GetControlTestsTool.name, - GetControlTestsTool.description, - GetControlTestsTool.parameters.shape, - getControlTests, + ListControlTestsTool.name, + ListControlTestsTool.description, + ListControlTestsTool.parameters.shape, + listControlTests, ); server.tool( - GetLibraryControlsTool.name, - GetLibraryControlsTool.description, - GetLibraryControlsTool.parameters.shape, - getLibraryControls, + ListLibraryControlsTool.name, + ListLibraryControlsTool.description, + ListLibraryControlsTool.parameters.shape, + listLibraryControls, ); server.tool( - GetControlDocumentsTool.name, - GetControlDocumentsTool.description, - GetControlDocumentsTool.parameters.shape, - getControlDocuments, + ListControlDocumentsTool.name, + ListControlDocumentsTool.description, + ListControlDocumentsTool.parameters.shape, + listControlDocuments, ); server.tool( - GetControlByIdTool.name, - GetControlByIdTool.description, - GetControlByIdTool.parameters.shape, - getControlById, + GetControlTool.name, + GetControlTool.description, + GetControlTool.parameters.shape, + getControl, ); server.tool( - GetRisksTool.name, - GetRisksTool.description, - GetRisksTool.parameters.shape, - getRisks, + ListRisksTool.name, + ListRisksTool.description, + ListRisksTool.parameters.shape, + listRisks, ); server.tool( - GetRiskByIdTool.name, - GetRiskByIdTool.description, - GetRiskByIdTool.parameters.shape, - getRiskById, + GetRiskTool.name, + GetRiskTool.description, + GetRiskTool.parameters.shape, + getRisk, ); server.tool( - GetIntegrationsTool.name, - GetIntegrationsTool.description, - GetIntegrationsTool.parameters.shape, - getIntegrations, + ListIntegrationsTool.name, + ListIntegrationsTool.description, + ListIntegrationsTool.parameters.shape, + listIntegrations, ); server.tool( - GetIntegrationByIdTool.name, - GetIntegrationByIdTool.description, - GetIntegrationByIdTool.parameters.shape, - getIntegrationById, + GetIntegrationTool.name, + GetIntegrationTool.description, + GetIntegrationTool.parameters.shape, + getIntegration, ); server.tool( - GetIntegrationResourceKindsTool.name, - GetIntegrationResourceKindsTool.description, - GetIntegrationResourceKindsTool.parameters.shape, - getIntegrationResourceKinds, + ListIntegrationResourceKindsTool.name, + ListIntegrationResourceKindsTool.description, + ListIntegrationResourceKindsTool.parameters.shape, + listIntegrationResourceKinds, ); server.tool( @@ -287,101 +287,101 @@ server.tool( ); server.tool( - GetIntegrationResourcesTool.name, - GetIntegrationResourcesTool.description, - GetIntegrationResourcesTool.parameters.shape, - getIntegrationResources, + ListIntegrationResourcesTool.name, + ListIntegrationResourcesTool.description, + ListIntegrationResourcesTool.parameters.shape, + listIntegrationResources, ); server.tool( - GetIntegrationResourceByIdTool.name, - GetIntegrationResourceByIdTool.description, - GetIntegrationResourceByIdTool.parameters.shape, - getIntegrationResourceById, + GetIntegrationResourceTool.name, + GetIntegrationResourceTool.description, + GetIntegrationResourceTool.parameters.shape, + getIntegrationResource, ); server.tool( - GetVendorsTool.name, - GetVendorsTool.description, - GetVendorsTool.parameters.shape, - getVendors, + ListVendorsTool.name, + ListVendorsTool.description, + ListVendorsTool.parameters.shape, + listVendors, ); server.tool( - GetVendorByIdTool.name, - GetVendorByIdTool.description, - GetVendorByIdTool.parameters.shape, - getVendorById, + GetVendorTool.name, + GetVendorTool.description, + GetVendorTool.parameters.shape, + getVendor, ); server.tool( - GetVendorDocumentsTool.name, - GetVendorDocumentsTool.description, - GetVendorDocumentsTool.parameters.shape, - getVendorDocuments, + ListVendorDocumentsTool.name, + ListVendorDocumentsTool.description, + ListVendorDocumentsTool.parameters.shape, + listVendorDocuments, ); server.tool( - GetVendorFindingsTool.name, - GetVendorFindingsTool.description, - GetVendorFindingsTool.parameters.shape, - getVendorFindings, + ListVendorFindingsTool.name, + ListVendorFindingsTool.description, + ListVendorFindingsTool.parameters.shape, + listVendorFindings, ); server.tool( - GetVendorSecurityReviewsTool.name, - GetVendorSecurityReviewsTool.description, - GetVendorSecurityReviewsTool.parameters.shape, - getVendorSecurityReviews, + ListVendorSecurityReviewsTool.name, + ListVendorSecurityReviewsTool.description, + ListVendorSecurityReviewsTool.parameters.shape, + listVendorSecurityReviews, ); server.tool( - GetVendorSecurityReviewByIdTool.name, - GetVendorSecurityReviewByIdTool.description, - GetVendorSecurityReviewByIdTool.parameters.shape, - getVendorSecurityReviewById, + GetVendorSecurityReviewTool.name, + GetVendorSecurityReviewTool.description, + GetVendorSecurityReviewTool.parameters.shape, + getVendorSecurityReview, ); server.tool( - GetVendorSecurityReviewDocumentsTool.name, - GetVendorSecurityReviewDocumentsTool.description, - GetVendorSecurityReviewDocumentsTool.parameters.shape, - getVendorSecurityReviewDocuments, + ListVendorSecurityReviewDocumentsTool.name, + ListVendorSecurityReviewDocumentsTool.description, + ListVendorSecurityReviewDocumentsTool.parameters.shape, + listVendorSecurityReviewDocuments, ); server.tool( - GetDocumentsTool.name, - GetDocumentsTool.description, - GetDocumentsTool.parameters.shape, - getDocuments, + ListDocumentsTool.name, + ListDocumentsTool.description, + ListDocumentsTool.parameters.shape, + listDocuments, ); server.tool( - GetDocumentByIdTool.name, - GetDocumentByIdTool.description, - GetDocumentByIdTool.parameters.shape, - getDocumentById, + GetDocumentTool.name, + GetDocumentTool.description, + GetDocumentTool.parameters.shape, + getDocument, ); server.tool( - GetDocumentControlsTool.name, - GetDocumentControlsTool.description, - GetDocumentControlsTool.parameters.shape, - getDocumentControls, + ListDocumentControlsTool.name, + ListDocumentControlsTool.description, + ListDocumentControlsTool.parameters.shape, + listDocumentControls, ); server.tool( - GetDocumentLinksTool.name, - GetDocumentLinksTool.description, - GetDocumentLinksTool.parameters.shape, - getDocumentLinks, + ListDocumentLinksTool.name, + ListDocumentLinksTool.description, + ListDocumentLinksTool.parameters.shape, + listDocumentLinks, ); server.tool( - GetDocumentUploadsTool.name, - GetDocumentUploadsTool.description, - GetDocumentUploadsTool.parameters.shape, - getDocumentUploads, + ListDocumentUploadsTool.name, + ListDocumentUploadsTool.description, + ListDocumentUploadsTool.parameters.shape, + listDocumentUploads, ); server.tool( @@ -392,122 +392,122 @@ server.tool( ); server.tool( - GetPoliciesTool.name, - GetPoliciesTool.description, - GetPoliciesTool.parameters.shape, - getPolicies, + ListPoliciesTool.name, + ListPoliciesTool.description, + ListPoliciesTool.parameters.shape, + listPolicies, ); server.tool( - GetPolicyByIdTool.name, - GetPolicyByIdTool.description, - GetPolicyByIdTool.parameters.shape, - getPolicyById, + GetPolicyTool.name, + GetPolicyTool.description, + GetPolicyTool.parameters.shape, + getPolicy, ); server.tool( - GetDiscoveredVendorsTool.name, - GetDiscoveredVendorsTool.description, - GetDiscoveredVendorsTool.parameters.shape, - getDiscoveredVendors, + ListDiscoveredVendorsTool.name, + ListDiscoveredVendorsTool.description, + ListDiscoveredVendorsTool.parameters.shape, + listDiscoveredVendors, ); server.tool( - GetDiscoveredVendorAccountsTool.name, - GetDiscoveredVendorAccountsTool.description, - GetDiscoveredVendorAccountsTool.parameters.shape, - getDiscoveredVendorAccounts, + ListDiscoveredVendorAccountsTool.name, + ListDiscoveredVendorAccountsTool.description, + ListDiscoveredVendorAccountsTool.parameters.shape, + listDiscoveredVendorAccounts, ); server.tool( - GetGroupsTool.name, - GetGroupsTool.description, - GetGroupsTool.parameters.shape, - getGroups, + ListGroupsTool.name, + ListGroupsTool.description, + ListGroupsTool.parameters.shape, + listGroups, ); server.tool( - GetGroupByIdTool.name, - GetGroupByIdTool.description, - GetGroupByIdTool.parameters.shape, - getGroupById, + GetGroupTool.name, + GetGroupTool.description, + GetGroupTool.parameters.shape, + getGroup, ); server.tool( - GetGroupPeopleTool.name, - GetGroupPeopleTool.description, - GetGroupPeopleTool.parameters.shape, - getGroupPeople, + ListGroupPeopleTool.name, + ListGroupPeopleTool.description, + ListGroupPeopleTool.parameters.shape, + listGroupPeople, ); server.tool( - GetPeopleTool.name, - GetPeopleTool.description, - GetPeopleTool.parameters.shape, - getPeople, + ListPeopleTool.name, + ListPeopleTool.description, + ListPeopleTool.parameters.shape, + listPeople, ); server.tool( - GetPersonByIdTool.name, - GetPersonByIdTool.description, - GetPersonByIdTool.parameters.shape, - getPersonById, + GetPersonTool.name, + GetPersonTool.description, + GetPersonTool.parameters.shape, + getPerson, ); server.tool( - GetVulnerabilitiesTool.name, - GetVulnerabilitiesTool.description, - GetVulnerabilitiesTool.parameters.shape, - getVulnerabilities, + ListVulnerabilitiesTool.name, + ListVulnerabilitiesTool.description, + ListVulnerabilitiesTool.parameters.shape, + listVulnerabilities, ); server.tool( - GetVulnerabilityByIdTool.name, - GetVulnerabilityByIdTool.description, - GetVulnerabilityByIdTool.parameters.shape, - getVulnerabilityById, + GetVulnerabilityTool.name, + GetVulnerabilityTool.description, + GetVulnerabilityTool.parameters.shape, + getVulnerability, ); server.tool( - GetVulnerabilityRemediationsTool.name, - GetVulnerabilityRemediationsTool.description, - GetVulnerabilityRemediationsTool.parameters.shape, - getVulnerabilityRemediations, + ListVulnerabilityRemediationsTool.name, + ListVulnerabilityRemediationsTool.description, + ListVulnerabilityRemediationsTool.parameters.shape, + listVulnerabilityRemediations, ); server.tool( - GetVulnerableAssetsTool.name, - GetVulnerableAssetsTool.description, - GetVulnerableAssetsTool.parameters.shape, - getVulnerableAssets, + ListVulnerableAssetsTool.name, + ListVulnerableAssetsTool.description, + ListVulnerableAssetsTool.parameters.shape, + listVulnerableAssets, ); server.tool( - GetVulnerableAssetByIdTool.name, - GetVulnerableAssetByIdTool.description, - GetVulnerableAssetByIdTool.parameters.shape, - getVulnerableAssetById, + GetVulnerableAssetTool.name, + GetVulnerableAssetTool.description, + GetVulnerableAssetTool.parameters.shape, + getVulnerableAsset, ); server.tool( - GetMonitoredComputersTool.name, - GetMonitoredComputersTool.description, - GetMonitoredComputersTool.parameters.shape, - getMonitoredComputers, + ListMonitoredComputersTool.name, + ListMonitoredComputersTool.description, + ListMonitoredComputersTool.parameters.shape, + listMonitoredComputers, ); server.tool( - GetMonitoredComputerByIdTool.name, - GetMonitoredComputerByIdTool.description, - GetMonitoredComputerByIdTool.parameters.shape, - getMonitoredComputerById, + GetMonitoredComputerTool.name, + GetMonitoredComputerTool.description, + GetMonitoredComputerTool.parameters.shape, + getMonitoredComputer, ); server.tool( - GetVendorRiskAttributesTool.name, - GetVendorRiskAttributesTool.description, - GetVendorRiskAttributesTool.parameters.shape, - getVendorRiskAttributes, + ListVendorRiskAttributesTool.name, + ListVendorRiskAttributesTool.description, + ListVendorRiskAttributesTool.parameters.shape, + listVendorRiskAttributes, ); server.tool( diff --git a/src/operations/controls.ts b/src/operations/controls.ts index cf56d41..1d7e0dd 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -9,7 +9,7 @@ import { CONTROL_ID_DESCRIPTION, } from "./global-descriptions.js"; -const GetControlsInput = z.object({ +const ListControlsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), frameworkMatchesAny: z @@ -20,64 +20,64 @@ const GetControlsInput = z.object({ .optional(), }); -export const GetControlsTool: Tool = { - name: "get_controls", +export const ListControlsTool: Tool = { + name: "list_controls", description: "List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. Optionally filter by specific frameworks using frameworkMatchesAny.", - parameters: GetControlsInput, + parameters: ListControlsInput, }; -const GetControlTestsInput = z.object({ +const ListControlTestsInput = z.object({ controlId: z.string().describe(CONTROL_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetControlTestsTool: Tool = { - name: "get_control_tests", +export const ListControlTestsTool: Tool = { + name: "list_control_tests", description: "List a control's tests. Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests.", - parameters: GetControlTestsInput, + parameters: ListControlTestsInput, }; -const GetLibraryControlsInput = z.object({ +const ListLibraryControlsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetLibraryControlsTool: Tool = { - name: "get_library_controls", +export const ListLibraryControlsTool: Tool = { + name: "list_library_controls", description: - "List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from get_controls which lists controls already in your account - this shows available controls you can implement.", - parameters: GetLibraryControlsInput, + "List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from list_controls which lists controls already in your account - this shows available controls you can implement.", + parameters: ListLibraryControlsInput, }; -const GetControlDocumentsInput = z.object({ +const ListControlDocumentsInput = z.object({ controlId: z.string().describe(CONTROL_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetControlDocumentsTool: Tool = { - name: "get_control_documents", +export const ListControlDocumentsTool: Tool = { + name: "list_control_documents", description: "List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence.", - parameters: GetControlDocumentsInput, + parameters: ListControlDocumentsInput, }; -const GetControlByIdInput = z.object({ +const GetControlInput = z.object({ controlId: z.string().describe(CONTROL_ID_DESCRIPTION), }); -export const GetControlByIdTool: Tool = { - name: "get_control_by_id", +export const GetControlTool: Tool = { + name: "get_control", description: - "Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from get_controls or get_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status.", - parameters: GetControlByIdInput, + "Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from list_controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status.", + parameters: GetControlInput, }; -export async function getControls( - args: z.infer, +export async function listControls( + args: z.infer, ): Promise { const url = new URL("/v1/controls", baseApiUrl()); @@ -113,8 +113,8 @@ export async function getControls( }; } -export async function getControlTests( - args: z.infer, +export async function listControlTests( + args: z.infer, ): Promise { const url = new URL(`/v1/controls/${args.controlId}/tests`, baseApiUrl()); @@ -145,8 +145,8 @@ export async function getControlTests( }; } -export async function getLibraryControls( - args: z.infer, +export async function listLibraryControls( + args: z.infer, ): Promise { const url = new URL("/v1/controls/controls-library", baseApiUrl()); @@ -177,8 +177,8 @@ export async function getLibraryControls( }; } -export async function getControlDocuments( - args: z.infer, +export async function listControlDocuments( + args: z.infer, ): Promise { const url = new URL(`/v1/controls/${args.controlId}/documents`, baseApiUrl()); @@ -209,8 +209,8 @@ export async function getControlDocuments( }; } -export async function getControlById( - args: z.infer, +export async function getControl( + args: z.infer, ): Promise { const url = new URL(`/v1/controls/${args.controlId}`, baseApiUrl()); diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts index 3216aa9..7ca039c 100644 --- a/src/operations/discovered-vendors.ts +++ b/src/operations/discovered-vendors.ts @@ -8,35 +8,35 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetDiscoveredVendorsInput = z.object({ +const ListDiscoveredVendorsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDiscoveredVendorsTool: Tool = +export const ListDiscoveredVendorsTool: Tool = { - name: "get_discovered_vendors", + name: "list_discovered_vendors", description: "List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding.", - parameters: GetDiscoveredVendorsInput, + parameters: ListDiscoveredVendorsInput, }; -const GetDiscoveredVendorAccountsInput = z.object({ +const ListDiscoveredVendorAccountsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDiscoveredVendorAccountsTool: Tool< - typeof GetDiscoveredVendorAccountsInput +export const ListDiscoveredVendorAccountsTool: Tool< + typeof ListDiscoveredVendorAccountsInput > = { - name: "get_discovered_vendor_accounts", + name: "list_discovered_vendor_accounts", description: "List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors.", - parameters: GetDiscoveredVendorAccountsInput, + parameters: ListDiscoveredVendorAccountsInput, }; -export async function getDiscoveredVendors( - args: z.infer, +export async function listDiscoveredVendors( + args: z.infer, ): Promise { const url = new URL("/v1/discovered-vendors", baseApiUrl()); @@ -67,8 +67,8 @@ export async function getDiscoveredVendors( }; } -export async function getDiscoveredVendorAccounts( - args: z.infer, +export async function listDiscoveredVendorAccounts( + args: z.infer, ): Promise { const url = new URL("/v1/discovered-vendors/accounts", baseApiUrl()); diff --git a/src/operations/documents.ts b/src/operations/documents.ts index cac24ca..a087c2a 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -9,66 +9,66 @@ import { DOCUMENT_ID_DESCRIPTION, } from "./global-descriptions.js"; -const GetDocumentsInput = z.object({ +const ListDocumentsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDocumentsTool: Tool = { - name: "get_documents", +export const ListDocumentsTool: Tool = { + name: "list_documents", description: "List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls.", - parameters: GetDocumentsInput, + parameters: ListDocumentsInput, }; -const GetDocumentByIdInput = z.object({ +const GetDocumentInput = z.object({ documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), }); -export const GetDocumentByIdTool: Tool = { - name: "get_document_by_id", +export const GetDocumentTool: Tool = { + name: "get_document", description: "Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from get_documents response. Returns complete document details including name, type, metadata, and compliance mappings.", - parameters: GetDocumentByIdInput, + parameters: GetDocumentInput, }; -const GetDocumentControlsInput = z.object({ +const ListDocumentControlsInput = z.object({ documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDocumentControlsTool: Tool = { - name: "get_document_controls", +export const ListDocumentControlsTool: Tool = { + name: "list_document_controls", description: "List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence.", - parameters: GetDocumentControlsInput, + parameters: ListDocumentControlsInput, }; -const GetDocumentLinksInput = z.object({ +const ListDocumentLinksInput = z.object({ documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDocumentLinksTool: Tool = { - name: "get_document_links", +export const ListDocumentLinksTool: Tool = { + name: "list_document_links", description: "List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence.", - parameters: GetDocumentLinksInput, + parameters: ListDocumentLinksInput, }; -const GetDocumentUploadsInput = z.object({ +const ListDocumentUploadsInput = z.object({ documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetDocumentUploadsTool: Tool = { - name: "get_document_uploads", +export const ListDocumentUploadsTool: Tool = { + name: "list_document_uploads", description: "List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation.", - parameters: GetDocumentUploadsInput, + parameters: ListDocumentUploadsInput, }; const DownloadDocumentFileInput = z.object({ @@ -88,8 +88,8 @@ export const DownloadDocumentFileTool: Tool = parameters: DownloadDocumentFileInput, }; -export async function getDocuments( - args: z.infer, +export async function listDocuments( + args: z.infer, ): Promise { const url = new URL("/v1/documents", baseApiUrl()); @@ -120,8 +120,8 @@ export async function getDocuments( }; } -export async function getDocumentById( - args: z.infer, +export async function getDocument( + args: z.infer, ): Promise { const url = new URL(`/v1/documents/${args.documentId}`, baseApiUrl()); @@ -145,8 +145,8 @@ export async function getDocumentById( }; } -export async function getDocumentControls( - args: z.infer, +export async function listDocumentControls( + args: z.infer, ): Promise { const url = new URL( `/v1/documents/${args.documentId}/controls`, @@ -180,8 +180,8 @@ export async function getDocumentControls( }; } -export async function getDocumentLinks( - args: z.infer, +export async function listDocumentLinks( + args: z.infer, ): Promise { const url = new URL(`/v1/documents/${args.documentId}/links`, baseApiUrl()); @@ -212,8 +212,8 @@ export async function getDocumentLinks( }; } -export async function getDocumentUploads( - args: z.infer, +export async function listDocumentUploads( + args: z.infer, ): Promise { const url = new URL(`/v1/documents/${args.documentId}/uploads`, baseApiUrl()); diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index 6b52435..8fbbdb1 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -9,45 +9,45 @@ import { FRAMEWORK_ID_DESCRIPTION, } from "./global-descriptions.js"; -const GetFrameworksInput = z.object({ +const ListFrameworksInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetFrameworksTool: Tool = { - name: "get_frameworks", +export const ListFrameworksTool: Tool = { + name: "list_frameworks", description: "List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state including status of controls, documents, and tests for each framework.", - parameters: GetFrameworksInput, + parameters: ListFrameworksInput, }; -const GetFrameworkControlsInput = z.object({ +const ListFrameworkControlsInput = z.object({ frameworkId: z.string().describe(FRAMEWORK_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetFrameworkControlsTool: Tool = +export const ListFrameworkControlsTool: Tool = { - name: "get_framework_controls", + name: "list_framework_controls", description: - "Get the detailed CONTROL REQUIREMENTS for a specific framework (requires frameworkId). Use this when you need the specific control details, requirements, and implementation guidance for a known framework like 'soc2' or 'iso27001'. This returns the actual security controls and their descriptions, NOT the framework list. Use get_frameworks first if you need to see available frameworks.", - parameters: GetFrameworkControlsInput, + "Get the detailed CONTROL REQUIREMENTS for a specific framework (requires frameworkId). Use this when you need the specific control details, requirements, and implementation guidance for a known framework like 'soc2' or 'iso27001'. This returns the actual security controls and their descriptions, NOT the framework list. Use list_frameworks first if you need to see available frameworks.", + parameters: ListFrameworkControlsInput, }; -const GetFrameworkByIdInput = z.object({ +const GetFrameworkInput = z.object({ frameworkId: z.string().describe(FRAMEWORK_ID_DESCRIPTION), }); -export const GetFrameworkByIdTool: Tool = { - name: "get_framework_by_id", +export const GetFrameworkTool: Tool = { + name: "get_framework", description: - "Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from get_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state.", - parameters: GetFrameworkByIdInput, + "Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state.", + parameters: GetFrameworkInput, }; -export async function getFrameworkControls( - args: z.infer, +export async function listFrameworkControls( + args: z.infer, ): Promise { const url = new URL( `/v1/frameworks/${args.frameworkId}/controls`, @@ -76,8 +76,8 @@ export async function getFrameworkControls( }; } -export async function getFrameworks( - args: z.infer, +export async function listFrameworks( + args: z.infer, ): Promise { const url = new URL("/v1/frameworks", baseApiUrl()); if (args.pageSize !== undefined) { @@ -104,8 +104,8 @@ export async function getFrameworks( }; } -export async function getFrameworkById( - args: z.infer, +export async function getFramework( + args: z.infer, ): Promise { const url = new URL(`/v1/frameworks/${args.frameworkId}`, baseApiUrl()); diff --git a/src/operations/groups.ts b/src/operations/groups.ts index a5c9d9a..641e5f5 100644 --- a/src/operations/groups.ts +++ b/src/operations/groups.ts @@ -8,19 +8,19 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetGroupsInput = z.object({ +const ListGroupsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetGroupsTool: Tool = { - name: "get_groups", +export const ListGroupsTool: Tool = { + name: "list_groups", description: "List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control.", - parameters: GetGroupsInput, + parameters: ListGroupsInput, }; -const GetGroupByIdInput = z.object({ +const GetGroupInput = z.object({ groupId: z .string() .describe( @@ -28,14 +28,14 @@ const GetGroupByIdInput = z.object({ ), }); -export const GetGroupByIdTool: Tool = { - name: "get_group_by_id", +export const GetGroupTool: Tool = { + name: "get_group", description: "Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from get_groups response. Returns complete group details including name, description, member count, and access permissions.", - parameters: GetGroupByIdInput, + parameters: GetGroupInput, }; -const GetGroupPeopleInput = z.object({ +const ListGroupPeopleInput = z.object({ groupId: z .string() .describe( @@ -45,15 +45,15 @@ const GetGroupPeopleInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetGroupPeopleTool: Tool = { - name: "get_group_people", +export const ListGroupPeopleTool: Tool = { + name: "list_group_people", description: "List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions.", - parameters: GetGroupPeopleInput, + parameters: ListGroupPeopleInput, }; -export async function getGroups( - args: z.infer, +export async function listGroups( + args: z.infer, ): Promise { const url = new URL("/v1/groups", baseApiUrl()); @@ -84,8 +84,8 @@ export async function getGroups( }; } -export async function getGroupById( - args: z.infer, +export async function getGroup( + args: z.infer, ): Promise { const url = new URL(`/v1/groups/${args.groupId}`, baseApiUrl()); @@ -109,8 +109,8 @@ export async function getGroupById( }; } -export async function getGroupPeople( - args: z.infer, +export async function listGroupPeople( + args: z.infer, ): Promise { const url = new URL(`/v1/groups/${args.groupId}/people`, baseApiUrl()); diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index ade3539..d66ef97 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -9,42 +9,42 @@ import { INTEGRATION_ID_DESCRIPTION, } from "./global-descriptions.js"; -const GetIntegrationsInput = z.object({ +const ListIntegrationsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetIntegrationsTool: Tool = { - name: "get_integrations", +export const ListIntegrationsTool: Tool = { + name: "list_integrations", description: "List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance.", - parameters: GetIntegrationsInput, + parameters: ListIntegrationsInput, }; -const GetIntegrationByIdInput = z.object({ +const GetIntegrationInput = z.object({ integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), }); -export const GetIntegrationByIdTool: Tool = { - name: "get_integration_by_id", +export const GetIntegrationTool: Tool = { + name: "get_integration", description: "Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from get_integrations response. Returns complete integration details including configuration, resource kinds, and connection status.", - parameters: GetIntegrationByIdInput, + parameters: GetIntegrationInput, }; -const GetIntegrationResourceKindsInput = z.object({ +const ListIntegrationResourceKindsInput = z.object({ integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetIntegrationResourceKindsTool: Tool< - typeof GetIntegrationResourceKindsInput +export const ListIntegrationResourceKindsTool: Tool< + typeof ListIntegrationResourceKindsInput > = { - name: "get_integration_resource_kinds", + name: "list_integration_resource_kinds", description: "List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor.", - parameters: GetIntegrationResourceKindsInput, + parameters: ListIntegrationResourceKindsInput, }; const GetIntegrationResourceKindDetailsInput = z.object({ @@ -71,16 +71,16 @@ const GetIntegrationResourcesInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetIntegrationResourcesTool: Tool< - typeof GetIntegrationResourcesInput +export const ListIntegrationResourcesTool: Tool< + typeof ListIntegrationResourcesInput > = { - name: "get_integration_resources", + name: "list_integration_resources", description: "List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration.", - parameters: GetIntegrationResourcesInput, + parameters: ListIntegrationResourcesInput, }; -const GetIntegrationResourceByIdInput = z.object({ +const GetIntegrationResourceInput = z.object({ integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), resourceId: z .string() @@ -89,17 +89,17 @@ const GetIntegrationResourceByIdInput = z.object({ ), }); -export const GetIntegrationResourceByIdTool: Tool< - typeof GetIntegrationResourceByIdInput +export const GetIntegrationResourceTool: Tool< + typeof GetIntegrationResourceInput > = { - name: "get_integration_resource_by_id", + name: "get_integration_resource", description: "Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration.", - parameters: GetIntegrationResourceByIdInput, + parameters: GetIntegrationResourceInput, }; -export async function getIntegrations( - args: z.infer, +export async function listIntegrations( + args: z.infer, ): Promise { const url = new URL("/v1/integrations", baseApiUrl()); @@ -130,8 +130,8 @@ export async function getIntegrations( }; } -export async function getIntegrationById( - args: z.infer, +export async function getIntegration( + args: z.infer, ): Promise { const url = new URL(`/v1/integrations/${args.integrationId}`, baseApiUrl()); @@ -155,8 +155,8 @@ export async function getIntegrationById( }; } -export async function getIntegrationResourceKinds( - args: z.infer, +export async function listIntegrationResourceKinds( + args: z.infer, ): Promise { const url = new URL( `/v1/integrations/${args.integrationId}/resource-kinds`, @@ -218,8 +218,8 @@ export async function getIntegrationResourceKindDetails( }; } -export async function getIntegrationResources( - args: z.infer, +export async function listIntegrationResources( + args: z.infer, ): Promise { const url = new URL( `/v1/integrations/${args.integrationId}/resources`, @@ -253,8 +253,8 @@ export async function getIntegrationResources( }; } -export async function getIntegrationResourceById( - args: z.infer, +export async function getIntegrationResource( + args: z.infer, ): Promise { const url = new URL( `/v1/integrations/${args.integrationId}/resources/${args.resourceId}`, diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts index a9295cb..349479a 100644 --- a/src/operations/monitored-computers.ts +++ b/src/operations/monitored-computers.ts @@ -8,21 +8,21 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetMonitoredComputersInput = z.object({ +const ListMonitoredComputersInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetMonitoredComputersTool: Tool< - typeof GetMonitoredComputersInput +export const ListMonitoredComputersTool: Tool< + typeof ListMonitoredComputersInput > = { - name: "get_monitored_computers", + name: "list_monitored_computers", description: "List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization.", - parameters: GetMonitoredComputersInput, + parameters: ListMonitoredComputersInput, }; -const GetMonitoredComputerByIdInput = z.object({ +const GetMonitoredComputerInput = z.object({ computerId: z .string() .describe( @@ -30,17 +30,17 @@ const GetMonitoredComputerByIdInput = z.object({ ), }); -export const GetMonitoredComputerByIdTool: Tool< - typeof GetMonitoredComputerByIdInput +export const GetMonitoredComputerTool: Tool< + typeof GetMonitoredComputerInput > = { - name: "get_monitored_computer_by_id", + name: "get_monitored_computer", description: "Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information.", - parameters: GetMonitoredComputerByIdInput, + parameters: GetMonitoredComputerInput, }; -export async function getMonitoredComputers( - args: z.infer, +export async function listMonitoredComputers( + args: z.infer, ): Promise { const url = new URL("/v1/monitored-computers", baseApiUrl()); @@ -71,8 +71,8 @@ export async function getMonitoredComputers( }; } -export async function getMonitoredComputerById( - args: z.infer, +export async function getMonitoredComputer( + args: z.infer, ): Promise { const url = new URL( `/v1/monitored-computers/${args.computerId}`, diff --git a/src/operations/people.ts b/src/operations/people.ts index 93a0518..f99c8cb 100644 --- a/src/operations/people.ts +++ b/src/operations/people.ts @@ -8,19 +8,19 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetPeopleInput = z.object({ +const ListPeopleInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetPeopleTool: Tool = { - name: "get_people", +export const ListPeopleTool: Tool = { + name: "list_people", description: "List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management.", - parameters: GetPeopleInput, + parameters: ListPeopleInput, }; -const GetPersonByIdInput = z.object({ +const GetPersonInput = z.object({ personId: z .string() .describe( @@ -28,15 +28,15 @@ const GetPersonByIdInput = z.object({ ), }); -export const GetPersonByIdTool: Tool = { - name: "get_person_by_id", +export const GetPersonTool: Tool = { + name: "get_person", description: "Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from get_people response. Returns complete person details including name, email, role, group memberships, and access permissions.", - parameters: GetPersonByIdInput, + parameters: GetPersonInput, }; -export async function getPeople( - args: z.infer, +export async function listPeople( + args: z.infer, ): Promise { const url = new URL("/v1/people", baseApiUrl()); @@ -67,8 +67,8 @@ export async function getPeople( }; } -export async function getPersonById( - args: z.infer, +export async function getPerson( + args: z.infer, ): Promise { const url = new URL(`/v1/people/${args.personId}`, baseApiUrl()); diff --git a/src/operations/policies.ts b/src/operations/policies.ts index 5fc3b60..48c218f 100644 --- a/src/operations/policies.ts +++ b/src/operations/policies.ts @@ -8,19 +8,19 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetPoliciesInput = z.object({ +const ListPoliciesInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetPoliciesTool: Tool = { - name: "get_policies", +export const ListPoliciesTool: Tool = { + name: "list_policies", description: "List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance.", - parameters: GetPoliciesInput, + parameters: ListPoliciesInput, }; -const GetPolicyByIdInput = z.object({ +const GetPolicyInput = z.object({ policyId: z .string() .describe( @@ -28,15 +28,15 @@ const GetPolicyByIdInput = z.object({ ), }); -export const GetPolicyByIdTool: Tool = { - name: "get_policy_by_id", +export const GetPolicyTool: Tool = { + name: "get_policy", description: "Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings.", - parameters: GetPolicyByIdInput, + parameters: GetPolicyInput, }; -export async function getPolicies( - args: z.infer, +export async function listPolicies( + args: z.infer, ): Promise { const url = new URL("/v1/policies", baseApiUrl()); @@ -67,8 +67,8 @@ export async function getPolicies( }; } -export async function getPolicyById( - args: z.infer, +export async function getPolicy( + args: z.infer, ): Promise { const url = new URL(`/v1/policies/${args.policyId}`, baseApiUrl()); diff --git a/src/operations/risks.ts b/src/operations/risks.ts index cae90e6..949de74 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -8,7 +8,7 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetRisksInput = z.object({ +const ListRisksInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), categoryMatchesAny: z @@ -19,13 +19,13 @@ const GetRisksInput = z.object({ ), }); -export const GetRisksTool: Tool = { - name: "get_risks", +export const ListRisksTool: Tool = { + name: "list_risks", description: "List all risk scenarios in your Vanta risk register.", - parameters: GetRisksInput, + parameters: ListRisksInput, }; -const GetRiskByIdInput = z.object({ +const GetRiskInput = z.object({ riskId: z .string() .describe( @@ -33,15 +33,15 @@ const GetRiskByIdInput = z.object({ ), }); -export const GetRiskByIdTool: Tool = { - name: "get_risk_by_id", +export const GetRiskTool: Tool = { + name: "get_risk", description: - "Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from get_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more.", - parameters: GetRiskByIdInput, + "Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from list_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more.", + parameters: GetRiskInput, }; -export async function getRisks( - args: z.infer, +export async function listRisks( + args: z.infer, ): Promise { const url = new URL("/v1/risk-scenarios", baseApiUrl()); if (args.pageSize !== undefined) { @@ -71,8 +71,8 @@ export async function getRisks( }; } -export async function getRiskById( - args: z.infer, +export async function getRisk( + args: z.infer, ): Promise { const url = new URL(`/v1/risk-scenarios/${args.riskId}`, baseApiUrl()); diff --git a/src/operations/tests.ts b/src/operations/tests.ts index 2a13772..eeae3da 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -8,8 +8,8 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -export async function getTests( - args: z.infer, +export async function listTests( + args: z.infer, ): Promise { const url = new URL("/v1/tests", baseApiUrl()); @@ -52,8 +52,8 @@ export async function getTests( }; } -export async function getTestEntities( - args: z.infer, +export async function listTestEntities( + args: z.infer, ): Promise { const url = new URL(`/v1/tests/${args.testId}/entities`, baseApiUrl()); if (args.pageSize !== undefined) { @@ -86,8 +86,8 @@ export async function getTestEntities( }; } -export async function getTestById( - args: z.infer, +export async function getTest( + args: z.infer, ): Promise { const url = new URL(`/v1/tests/${args.testId}`, baseApiUrl()); @@ -127,7 +127,7 @@ const FRAMEWORK_FILTER_DESCRIPTION = `Filter by framework. Non-exhaustive exampl const CONTROL_FILTER_DESCRIPTION = `Filter by control. Generally will only be known if pulled from the /v1/controls endpoint.`; -export const GetTestsInput = z.object({ +export const ListTestsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), statusFilter: z.string().describe(TEST_STATUS_FILTER_DESCRIPTION).optional(), @@ -139,13 +139,13 @@ export const GetTestsInput = z.object({ controlFilter: z.string().describe(CONTROL_FILTER_DESCRIPTION).optional(), }); -export const GetTestsTool: Tool = { - name: "get_tests", +export const ListTestsTool: Tool = { + name: "list_tests", description: TOOL_DESCRIPTION, - parameters: GetTestsInput, + parameters: ListTestsInput, }; -const GetTestEntitiesInput = z.object({ +const ListTestEntitiesInput = z.object({ testId: z.string().describe("Lowercase with hyphens"), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), @@ -155,22 +155,22 @@ const GetTestEntitiesInput = z.object({ .optional(), }); -export const GetTestEntitiesTool: Tool = { - name: "get_test_entities", +export const ListTestEntitiesTool: Tool = { + name: "list_test_entities", description: `Get the specific failing resources (entities) for a known test ID. Use this when you already know the test name/ID and need to see which specific infrastructure resources are failing that test. For example, if you know "aws-security-groups-open-to-world" test is failing, this returns the actual security - group IDs that are failing. Requires a specific testId parameter. Do NOT use this for general test discovery - use get_tests for that.`, - parameters: GetTestEntitiesInput, + group IDs that are failing. Requires a specific testId parameter. Do NOT use this for general test discovery - use list_tests for that.`, + parameters: ListTestEntitiesInput, }; -const GetTestByIdInput = z.object({ +const GetTestInput = z.object({ testId: z.string().describe("Lowercase with hyphens"), }); -export const GetTestByIdTool: Tool = { - name: "get_test_by_id", +export const GetTestTool: Tool = { + name: "get_test", description: `Get the details of a single specific test when its ID is known. The ID of a test can be - found in the response from get_tests or from the URL of the test in your browser after /tests/.`, - parameters: GetTestByIdInput, + found in the response from list_tests or from the URL of the test in your browser after /tests/.`, + parameters: GetTestInput, }; diff --git a/src/operations/vendor-risk-attributes.ts b/src/operations/vendor-risk-attributes.ts index 3034f12..d8b6376 100644 --- a/src/operations/vendor-risk-attributes.ts +++ b/src/operations/vendor-risk-attributes.ts @@ -8,22 +8,22 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetVendorRiskAttributesInput = z.object({ +const ListVendorRiskAttributesInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorRiskAttributesTool: Tool< - typeof GetVendorRiskAttributesInput +export const ListVendorRiskAttributesTool: Tool< + typeof ListVendorRiskAttributesInput > = { - name: "get_vendor_risk_attributes", + name: "list_vendor_risk_attributes", description: "List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization.", - parameters: GetVendorRiskAttributesInput, + parameters: ListVendorRiskAttributesInput, }; -export async function getVendorRiskAttributes( - args: z.infer, +export async function listVendorRiskAttributes( + args: z.infer, ): Promise { const url = new URL("/v1/vendor-risk-attributes", baseApiUrl()); diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index 1944546..4c86739 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -9,71 +9,71 @@ import { VENDOR_ID_DESCRIPTION, } from "./global-descriptions.js"; -const GetVendorsInput = z.object({ +const ListVendorsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorsTool: Tool = { - name: "get_vendors", +export const ListVendorsTool: Tool = { + name: "list_vendors", description: "List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors.", - parameters: GetVendorsInput, + parameters: ListVendorsInput, }; -const GetVendorByIdInput = z.object({ +const GetVendorInput = z.object({ vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), }); -export const GetVendorByIdTool: Tool = { - name: "get_vendor_by_id", +export const GetVendorTool: Tool = { + name: "get_vendor", description: "Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from get_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status.", - parameters: GetVendorByIdInput, + parameters: GetVendorInput, }; -const GetVendorDocumentsInput = z.object({ +const ListVendorDocumentsInput = z.object({ vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorDocumentsTool: Tool = { - name: "get_vendor_documents", +export const ListVendorDocumentsTool: Tool = { + name: "list_vendor_documents", description: "List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence.", - parameters: GetVendorDocumentsInput, + parameters: ListVendorDocumentsInput, }; -const GetVendorFindingsInput = z.object({ +const ListVendorFindingsInput = z.object({ vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorFindingsTool: Tool = { - name: "get_vendor_findings", +export const ListVendorFindingsTool: Tool = { + name: "list_vendor_findings", description: "List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor.", - parameters: GetVendorFindingsInput, + parameters: ListVendorFindingsInput, }; -const GetVendorSecurityReviewsInput = z.object({ +const ListVendorSecurityReviewsInput = z.object({ vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorSecurityReviewsTool: Tool< - typeof GetVendorSecurityReviewsInput +export const ListVendorSecurityReviewsTool: Tool< + typeof ListVendorSecurityReviewsInput > = { - name: "get_vendor_security_reviews", + name: "list_vendor_security_reviews", description: "Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities.", - parameters: GetVendorSecurityReviewsInput, + parameters: ListVendorSecurityReviewsInput, }; -const GetVendorSecurityReviewByIdInput = z.object({ +const GetVendorSecurityReviewInput = z.object({ vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), securityReviewId: z .string() @@ -82,16 +82,16 @@ const GetVendorSecurityReviewByIdInput = z.object({ ), }); -export const GetVendorSecurityReviewByIdTool: Tool< - typeof GetVendorSecurityReviewByIdInput +export const GetVendorSecurityReviewTool: Tool< + typeof GetVendorSecurityReviewInput > = { - name: "get_vendor_security_review_by_id", + name: "get_vendor_security_review", description: "Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations.", - parameters: GetVendorSecurityReviewByIdInput, + parameters: GetVendorSecurityReviewInput, }; -const GetVendorSecurityReviewDocumentsInput = z.object({ +const ListVendorSecurityReviewDocumentsInput = z.object({ vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), securityReviewId: z .string() @@ -102,17 +102,17 @@ const GetVendorSecurityReviewDocumentsInput = z.object({ pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVendorSecurityReviewDocumentsTool: Tool< - typeof GetVendorSecurityReviewDocumentsInput +export const ListVendorSecurityReviewDocumentsTool: Tool< + typeof ListVendorSecurityReviewDocumentsInput > = { - name: "get_vendor_security_review_documents", + name: "list_vendor_security_review_documents", description: "Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment.", - parameters: GetVendorSecurityReviewDocumentsInput, + parameters: ListVendorSecurityReviewDocumentsInput, }; -export async function getVendors( - args: z.infer, +export async function listVendors( + args: z.infer, ): Promise { const url = new URL("/v1/vendors", baseApiUrl()); @@ -143,8 +143,8 @@ export async function getVendors( }; } -export async function getVendorById( - args: z.infer, +export async function getVendor( + args: z.infer, ): Promise { const url = new URL(`/v1/vendors/${args.vendorId}`, baseApiUrl()); @@ -168,8 +168,8 @@ export async function getVendorById( }; } -export async function getVendorDocuments( - args: z.infer, +export async function listVendorDocuments( + args: z.infer, ): Promise { const url = new URL(`/v1/vendors/${args.vendorId}/documents`, baseApiUrl()); @@ -200,8 +200,8 @@ export async function getVendorDocuments( }; } -export async function getVendorFindings( - args: z.infer, +export async function listVendorFindings( + args: z.infer, ): Promise { const url = new URL(`/v1/vendors/${args.vendorId}/findings`, baseApiUrl()); @@ -232,8 +232,8 @@ export async function getVendorFindings( }; } -export async function getVendorSecurityReviews( - args: z.infer, +export async function listVendorSecurityReviews( + args: z.infer, ): Promise { const url = new URL( `/v1/vendors/${args.vendorId}/security-reviews`, @@ -267,8 +267,8 @@ export async function getVendorSecurityReviews( }; } -export async function getVendorSecurityReviewById( - args: z.infer, +export async function getVendorSecurityReview( + args: z.infer, ): Promise { const url = new URL( `/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}`, @@ -295,8 +295,8 @@ export async function getVendorSecurityReviewById( }; } -export async function getVendorSecurityReviewDocuments( - args: z.infer, +export async function listVendorSecurityReviewDocuments( + args: z.infer, ): Promise { const url = new URL( `/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}/documents`, diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index dbde203..57cec32 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -8,19 +8,19 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetVulnerabilitiesInput = z.object({ +const ListVulnerabilitiesInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVulnerabilitiesTool: Tool = { - name: "get_vulnerabilities", +export const ListVulnerabilitiesTool: Tool = { + name: "list_vulnerabilities", description: "Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications.", - parameters: GetVulnerabilitiesInput, + parameters: ListVulnerabilitiesInput, }; -const GetVulnerabilityByIdInput = z.object({ +const GetVulnerabilityInput = z.object({ vulnerabilityId: z .string() .describe( @@ -28,16 +28,16 @@ const GetVulnerabilityByIdInput = z.object({ ), }); -export const GetVulnerabilityByIdTool: Tool = +export const GetVulnerabilityTool: Tool = { - name: "get_vulnerability_by_id", + name: "get_vulnerability", description: - "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from get_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status.", - parameters: GetVulnerabilityByIdInput, + "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status.", + parameters: GetVulnerabilityInput, }; -export async function getVulnerabilities( - args: z.infer, +export async function listVulnerabilities( + args: z.infer, ): Promise { const url = new URL("/v1/vulnerabilities", baseApiUrl()); @@ -68,8 +68,8 @@ export async function getVulnerabilities( }; } -export async function getVulnerabilityById( - args: z.infer, +export async function getVulnerability( + args: z.infer, ): Promise { const url = new URL( `/v1/vulnerabilities/${args.vulnerabilityId}`, diff --git a/src/operations/vulnerability-remediations.ts b/src/operations/vulnerability-remediations.ts index 86d9ed9..2ce0233 100644 --- a/src/operations/vulnerability-remediations.ts +++ b/src/operations/vulnerability-remediations.ts @@ -8,22 +8,22 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetVulnerabilityRemediationsInput = z.object({ +const ListVulnerabilityRemediationsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVulnerabilityRemediationsTool: Tool< - typeof GetVulnerabilityRemediationsInput +export const ListVulnerabilityRemediationsTool: Tool< + typeof ListVulnerabilityRemediationsInput > = { - name: "get_vulnerability_remediations", + name: "list_vulnerability_remediations", description: "List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues.", - parameters: GetVulnerabilityRemediationsInput, + parameters: ListVulnerabilityRemediationsInput, }; -export async function getVulnerabilityRemediations( - args: z.infer, +export async function listVulnerabilityRemediations( + args: z.infer, ): Promise { const url = new URL("/v1/vulnerability-remediations", baseApiUrl()); diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts index 9c7161e..d43001c 100644 --- a/src/operations/vulnerable-assets.ts +++ b/src/operations/vulnerable-assets.ts @@ -8,19 +8,19 @@ import { PAGE_CURSOR_DESCRIPTION, } from "./global-descriptions.js"; -const GetVulnerableAssetsInput = z.object({ +const ListVulnerableAssetsInput = z.object({ pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); -export const GetVulnerableAssetsTool: Tool = { - name: "get_vulnerable_assets", +export const ListVulnerableAssetsTool: Tool = { + name: "list_vulnerable_assets", description: "List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts.", - parameters: GetVulnerableAssetsInput, + parameters: ListVulnerableAssetsInput, }; -const GetVulnerableAssetByIdInput = z.object({ +const GetVulnerableAssetInput = z.object({ vulnerableAssetId: z .string() .describe( @@ -28,17 +28,17 @@ const GetVulnerableAssetByIdInput = z.object({ ), }); -export const GetVulnerableAssetByIdTool: Tool< - typeof GetVulnerableAssetByIdInput +export const GetVulnerableAssetTool: Tool< + typeof GetVulnerableAssetInput > = { - name: "get_vulnerable_asset_by_id", + name: "get_vulnerable_asset", description: "Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status.", - parameters: GetVulnerableAssetByIdInput, + parameters: GetVulnerableAssetInput, }; -export async function getVulnerableAssets( - args: z.infer, +export async function listVulnerableAssets( + args: z.infer, ): Promise { const url = new URL("/v1/vulnerable-assets", baseApiUrl()); @@ -69,8 +69,8 @@ export async function getVulnerableAssets( }; } -export async function getVulnerableAssetById( - args: z.infer, +export async function getVulnerableAsset( + args: z.infer, ): Promise { const url = new URL( `/v1/vulnerable-assets/${args.vulnerableAssetId}`, From 00ff7130fa164184cf67e394bea2c50ccbabe9cf Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Wed, 24 Sep 2025 15:30:42 -0400 Subject: [PATCH 17/24] refactor: add comprehensive get endpoints and improve DRY patterns - Create reusable utility functions for common API patterns - Standardize schema creation with createIdSchema and createIdWithPaginationSchema helpers - Consolidate pagination and authentication logic - Add comprehensive documentation for all new endpoints - Update README with complete tool reference tables --- .gitignore | 5 +- README.md | 298 ++++----- src/eval/eval.ts | 354 +++++------ src/index.ts | 72 +-- src/operations/README.md | 491 +++++++++++++++ src/operations/controls.ts | 221 ++----- src/operations/discovered-vendors.ts | 111 ++-- src/operations/documents.ts | 260 +++----- src/operations/frameworks.ts | 132 ++-- src/operations/groups.ts | 137 +--- src/operations/integrations.ts | 274 +++----- src/operations/monitored-computers.ts | 100 +-- src/operations/people.ts | 80 +-- src/operations/policies.ts | 80 +-- src/operations/risks.ts | 79 +-- src/operations/tests.ts | 213 ++----- src/operations/trust-centers.ts | 618 ++++++------------- src/operations/utils.ts | 179 ++++++ src/operations/vendor-risk-attributes.ts | 46 +- src/operations/vendors.ts | 311 +++------- src/operations/vulnerabilities.ts | 98 +-- src/operations/vulnerability-remediations.ts | 46 +- src/operations/vulnerable-assets.ts | 100 +-- 23 files changed, 1804 insertions(+), 2501 deletions(-) create mode 100644 src/operations/README.md diff --git a/.gitignore b/.gitignore index 6d20071..83ca4f2 100644 --- a/.gitignore +++ b/.gitignore @@ -139,4 +139,7 @@ node_modules/ build/ # Claude Code generated files -CLAUDE.md \ No newline at end of file +CLAUDE.md + +# backup files +*.bak* \ No newline at end of file diff --git a/README.md b/README.md index 8ef9595..3e41f1f 100644 --- a/README.md +++ b/README.md @@ -15,13 +15,13 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - View documents providing evidence for specific security controls - Understand which automated tests monitor compliance for specific controls -| Tool Name | Description | -| --------- | ----------- | -| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. | -| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Returns test details, current status, and any failing entities for the control's tests. | -| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. | -| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. | -| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. | +| Tool Name | Description | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Returns test details, current status, and any failing entities for the control's tests. | +| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. | +| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. | ### Discovered Vendors @@ -30,10 +30,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Understand vendor relationships and account structures before converting to managed vendors - Streamline vendor risk assessment workflows by identifying unmanaged vendor relationships -| Tool Name | Description | -| --------- | ----------- | -| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. | -| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. | +| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. | ### Documents @@ -44,14 +44,14 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all files and uploads attached to documents for compliance documentation - Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata -| Tool Name | Description | -| --------- | ----------- | -| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. | -| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. | -| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. | -| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. | -| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. | -| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload with automatic MIME type handling. | +| Tool Name | Description | +| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. | +| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. | +| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. | +| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. | +| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. | +| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload with automatic MIME type handling. | ### Frameworks @@ -60,11 +60,11 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Get detailed security control requirements for specific compliance frameworks - Access implementation guidance and current compliance status for framework controls -| Tool Name | Description | -| --------- | ----------- | -| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. | +| Tool Name | Description | +| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. | | [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. | -| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. | +| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. | ### Groups @@ -72,11 +72,11 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Get detailed group information including member counts and access permissions - View group membership to understand who has group-based access permissions -| Tool Name | Description | -| --------- | ----------- | -| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. | -| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. | -| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. | +| Tool Name | Description | +| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. | +| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. | +| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. | ### Integrations @@ -89,14 +89,14 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all infrastructure resources discovered by integrations - Access detailed resource information including metadata, compliance status, and configuration -| Tool Name | Description | -| --------- | ----------- | -| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist. | -| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. | -| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. | -| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. | -| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. | -| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist. | +| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. | +| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. | +| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. | +| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. | +| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. | ### Monitored Computers @@ -104,10 +104,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access detailed computer information including hostnames, operating systems, and security status - Manage endpoint security and compliance across diverse computing environments -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. | -| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. | +| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. | ### People @@ -115,10 +115,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access detailed person information including roles, email addresses, and group memberships - Manage organizational structure and access control through comprehensive people data -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | | [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. | -| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. | +| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. | ### Policies @@ -127,10 +127,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access organizational policies for security, privacy, and operational governance - View policy metadata including names, types, and associated compliance frameworks -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. | -| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. | +| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. | ### Risks @@ -138,10 +138,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more - Filterable by risk category (Access Control, Cryptography, Privacy, and many others) -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. | -| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. | +| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. | ### Tests @@ -150,11 +150,11 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Get specific resources (entities) that are failing particular security tests - Essential for understanding exactly which infrastructure components need remediation -| Tool Name | Description | -| --------- | ----------- | -| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status, cloud integration, or compliance framework. Returns test results showing which security controls are passing or failing. | -| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. Essential for understanding exactly which infrastructure components need remediation. | -| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the list_tests response or from the address bar of your browser. | +| Tool Name | Description | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status, cloud integration, or compliance framework. Returns test results showing which security controls are passing or failing. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. Essential for understanding exactly which infrastructure components need remediation. | +| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the list_tests response or from the address bar of your browser. | ### Trust Centers @@ -167,20 +167,20 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Provide downloadable resources including compliance documents and certifications - Enable customer self-service access to compliance and security information -| Tool Name | Description | -| --------- | ----------- | -| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | -| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | -| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | -| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | -| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | -| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | -| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | -| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | -| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | -| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | -| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | -| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | +| Tool Name | Description | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | +| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | +| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | +| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | +| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | +| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | +| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | +| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | +| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | +| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | +| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | +| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | ### Vendor Risk Attributes @@ -188,8 +188,8 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Categorize and evaluate vendor risks using standardized risk assessment criteria - Access risk attribute IDs, names, categories, and assessment criteria for vendor risk management -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. | ### Vendors @@ -204,33 +204,33 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Get detailed information about specific vendor security reviews - Access supporting documentation and reports for security assessments -| Tool Name | Description | -| --------- | ----------- | -| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. | -| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. | -| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. | -| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. | -| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. | -| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. | -| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. | +| Tool Name | Description | +| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. | +| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. | +| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. | +| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. | +| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. | +| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. | +| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. | ### Vulnerabilities - Monitor all vulnerabilities detected across your infrastructure and applications - Access detailed vulnerability information including CVE data, severity levels, and affected assets -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. | -| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. | +| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. | ### Vulnerability Remediations - Track vulnerability remediation efforts and timelines for security management - Ensure timely resolution of security issues through comprehensive remediation tracking -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. | ### Vulnerable Assets @@ -238,10 +238,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Identify vulnerable assets and understand their security status - Prioritize security efforts based on asset vulnerability associations and risk levels -| Tool Name | Description | -| --------- | ----------- | +| Tool Name | Description | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. | -| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. | +| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. | ### Multi-Region Support @@ -250,69 +250,69 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid ## Tools -| Tool Name | Description | -| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | -| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | -| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | -| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | -| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | -| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | -| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | -| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | -| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from list_controls which lists controls already in your account - this shows available controls you can implement. | -| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | -| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from list_controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | -| [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | -| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from list_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | -| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | -| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from list_integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | -| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | -| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | -| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | -| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | -| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | -| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from list_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | -| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | -| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | -| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | -| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | -| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | -| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | -| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from list_documents response. Returns complete document details including name, type, metadata, and compliance mappings. | -| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | -| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | -| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | -| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | -| [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | -| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from list_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | -| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | -| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | -| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | -| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from list_groups response. Returns complete group details including name, description, member count, and access permissions. | -| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | -| [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | -| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from list_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | -| [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | -| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | -| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | -| [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | -| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from list_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | -| [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | -| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from list_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | -| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | -| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | -| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | -| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | -| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | -| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | -| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | -| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | -| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | -| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | -| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | -| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | -| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | +| Tool Name | Description | +| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | +| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | +| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | +| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | +| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | +| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | +| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from list_controls which lists controls already in your account - this shows available controls you can implement. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | +| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from list_controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | +| [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | +| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from list_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | +| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | +| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from list_integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | +| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | +| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | +| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | +| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | +| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | +| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from list_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | +| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | +| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | +| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | +| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | +| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | +| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | +| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from list_documents response. Returns complete document details including name, type, metadata, and compliance mappings. | +| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | +| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | +| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | +| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | +| [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | +| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from list_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | +| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | +| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | +| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | +| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from list_groups response. Returns complete group details including name, description, member count, and access permissions. | +| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | +| [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | +| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from list_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | +| [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | +| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | +| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | +| [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | +| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from list_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | +| [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | +| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from list_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | +| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | +| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | +| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | +| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | +| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | +| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | +| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | +| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | +| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | +| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | +| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | +| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | +| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | ## Configuration diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 4ec14eb..dc66868 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -1,69 +1,69 @@ import OpenAI from "openai"; import { zodToJsonSchema } from "zod-to-json-schema"; -import { GetTestsTool, GetTestEntitiesTool } from "../operations/tests.js"; +import { ListTestsTool, ListTestEntitiesTool } from "../operations/tests.js"; import { - GetFrameworksTool, - GetFrameworkControlsTool, - GetFrameworkByIdTool, + ListFrameworksTool, + ListFrameworkControlsTool, + GetFrameworkTool, } from "../operations/frameworks.js"; import { - GetControlsTool, - GetControlTestsTool, - GetLibraryControlsTool, - GetControlDocumentsTool, - GetControlByIdTool, + ListControlsTool, + ListControlTestsTool, + ListLibraryControlsTool, + ListControlDocumentsTool, + GetControlTool, } from "../operations/controls.js"; -import { GetRisksTool, GetRiskByIdTool } from "../operations/risks.js"; +import { ListRisksTool, GetRiskTool } from "../operations/risks.js"; import { - GetIntegrationsTool, - GetIntegrationByIdTool, + ListIntegrationsTool, + GetIntegrationTool, } from "../operations/integrations.js"; -import { GetVendorsTool, GetVendorByIdTool } from "../operations/vendors.js"; +import { ListVendorsTool, GetVendorTool } from "../operations/vendors.js"; import { - GetDocumentsTool, - GetDocumentByIdTool, - GetDocumentControlsTool, - GetDocumentLinksTool, - GetDocumentUploadsTool, + ListDocumentsTool, + GetDocumentTool, + ListDocumentControlsTool, + ListDocumentLinksTool, + ListDocumentUploadsTool, DownloadDocumentFileTool, } from "../operations/documents.js"; -import { GetPoliciesTool, GetPolicyByIdTool } from "../operations/policies.js"; +import { ListPoliciesTool, GetPolicyTool } from "../operations/policies.js"; import { - GetDiscoveredVendorsTool, - GetDiscoveredVendorAccountsTool, + ListDiscoveredVendorsTool, + ListDiscoveredVendorAccountsTool, } from "../operations/discovered-vendors.js"; import { - GetGroupsTool, - GetGroupByIdTool, - GetGroupPeopleTool, + ListGroupsTool, + GetGroupTool, + ListGroupPeopleTool, } from "../operations/groups.js"; -import { GetPeopleTool, GetPersonByIdTool } from "../operations/people.js"; +import { ListPeopleTool, GetPersonTool } from "../operations/people.js"; import { - GetVulnerabilitiesTool, - GetVulnerabilityByIdTool, + ListVulnerabilitiesTool, + GetVulnerabilityTool, } from "../operations/vulnerabilities.js"; -import { GetVulnerabilityRemediationsTool } from "../operations/vulnerability-remediations.js"; +import { ListVulnerabilityRemediationsTool } from "../operations/vulnerability-remediations.js"; import { - GetVulnerableAssetsTool, - GetVulnerableAssetByIdTool, + ListVulnerableAssetsTool, + GetVulnerableAssetTool, } from "../operations/vulnerable-assets.js"; import { - GetMonitoredComputersTool, - GetMonitoredComputerByIdTool, + ListMonitoredComputersTool, + GetMonitoredComputerTool, } from "../operations/monitored-computers.js"; -import { GetVendorRiskAttributesTool } from "../operations/vendor-risk-attributes.js"; +import { ListVendorRiskAttributesTool } from "../operations/vendor-risk-attributes.js"; import { GetTrustCenterTool, - GetTrustCenterAccessRequestsTool, + ListTrustCenterAccessRequestsTool, GetTrustCenterAccessRequestTool, - GetTrustCenterViewerActivityEventsTool, - GetTrustCenterControlCategoriesTool, + ListTrustCenterViewerActivityEventsTool, + ListTrustCenterControlCategoriesTool, GetTrustCenterControlCategoryTool, - GetTrustCenterControlsTool, + ListTrustCenterControlsTool, GetTrustCenterControlTool, - GetTrustCenterFaqsTool, + ListTrustCenterFaqsTool, GetTrustCenterFaqTool, - GetTrustCenterResourcesTool, + ListTrustCenterResourcesTool, GetTrustCenterDocumentTool, } from "../operations/trust-centers.js"; @@ -72,169 +72,169 @@ const tools = [ { type: "function" as const, function: { - name: GetTestsTool.name, - description: GetTestsTool.description, - parameters: zodToJsonSchema(GetTestsTool.parameters), + name: ListTestsTool.name, + description: ListTestsTool.description, + parameters: zodToJsonSchema(ListTestsTool.parameters), }, }, { type: "function" as const, function: { - name: GetTestEntitiesTool.name, - description: GetTestEntitiesTool.description, - parameters: zodToJsonSchema(GetTestEntitiesTool.parameters), + name: ListTestEntitiesTool.name, + description: ListTestEntitiesTool.description, + parameters: zodToJsonSchema(ListTestEntitiesTool.parameters), }, }, { type: "function" as const, function: { - name: GetFrameworksTool.name, - description: GetFrameworksTool.description, - parameters: zodToJsonSchema(GetFrameworksTool.parameters), + name: ListFrameworksTool.name, + description: ListFrameworksTool.description, + parameters: zodToJsonSchema(ListFrameworksTool.parameters), }, }, { type: "function" as const, function: { - name: GetFrameworkControlsTool.name, - description: GetFrameworkControlsTool.description, - parameters: zodToJsonSchema(GetFrameworkControlsTool.parameters), + name: ListFrameworkControlsTool.name, + description: ListFrameworkControlsTool.description, + parameters: zodToJsonSchema(ListFrameworkControlsTool.parameters), }, }, { type: "function" as const, function: { - name: GetControlsTool.name, - description: GetControlsTool.description, - parameters: zodToJsonSchema(GetControlsTool.parameters), + name: ListControlsTool.name, + description: ListControlsTool.description, + parameters: zodToJsonSchema(ListControlsTool.parameters), }, }, { type: "function" as const, function: { - name: GetControlTestsTool.name, - description: GetControlTestsTool.description, - parameters: zodToJsonSchema(GetControlTestsTool.parameters), + name: ListControlTestsTool.name, + description: ListControlTestsTool.description, + parameters: zodToJsonSchema(ListControlTestsTool.parameters), }, }, { type: "function" as const, function: { - name: GetLibraryControlsTool.name, - description: GetLibraryControlsTool.description, - parameters: zodToJsonSchema(GetLibraryControlsTool.parameters), + name: ListLibraryControlsTool.name, + description: ListLibraryControlsTool.description, + parameters: zodToJsonSchema(ListLibraryControlsTool.parameters), }, }, { type: "function" as const, function: { - name: GetControlDocumentsTool.name, - description: GetControlDocumentsTool.description, - parameters: zodToJsonSchema(GetControlDocumentsTool.parameters), + name: ListControlDocumentsTool.name, + description: ListControlDocumentsTool.description, + parameters: zodToJsonSchema(ListControlDocumentsTool.parameters), }, }, { type: "function" as const, function: { - name: GetControlByIdTool.name, - description: GetControlByIdTool.description, - parameters: zodToJsonSchema(GetControlByIdTool.parameters), + name: GetControlTool.name, + description: GetControlTool.description, + parameters: zodToJsonSchema(GetControlTool.parameters), }, }, { type: "function" as const, function: { - name: GetRisksTool.name, - description: GetRisksTool.description, - parameters: zodToJsonSchema(GetRisksTool.parameters), + name: ListRisksTool.name, + description: ListRisksTool.description, + parameters: zodToJsonSchema(ListRisksTool.parameters), }, }, { type: "function" as const, function: { - name: GetRiskByIdTool.name, - description: GetRiskByIdTool.description, - parameters: zodToJsonSchema(GetRiskByIdTool.parameters), + name: GetRiskTool.name, + description: GetRiskTool.description, + parameters: zodToJsonSchema(GetRiskTool.parameters), }, }, { type: "function" as const, function: { - name: GetFrameworkByIdTool.name, - description: GetFrameworkByIdTool.description, - parameters: zodToJsonSchema(GetFrameworkByIdTool.parameters), + name: GetFrameworkTool.name, + description: GetFrameworkTool.description, + parameters: zodToJsonSchema(GetFrameworkTool.parameters), }, }, { type: "function" as const, function: { - name: GetIntegrationsTool.name, - description: GetIntegrationsTool.description, - parameters: zodToJsonSchema(GetIntegrationsTool.parameters), + name: ListIntegrationsTool.name, + description: ListIntegrationsTool.description, + parameters: zodToJsonSchema(ListIntegrationsTool.parameters), }, }, { type: "function" as const, function: { - name: GetIntegrationByIdTool.name, - description: GetIntegrationByIdTool.description, - parameters: zodToJsonSchema(GetIntegrationByIdTool.parameters), + name: GetIntegrationTool.name, + description: GetIntegrationTool.description, + parameters: zodToJsonSchema(GetIntegrationTool.parameters), }, }, { type: "function" as const, function: { - name: GetVendorsTool.name, - description: GetVendorsTool.description, - parameters: zodToJsonSchema(GetVendorsTool.parameters), + name: ListVendorsTool.name, + description: ListVendorsTool.description, + parameters: zodToJsonSchema(ListVendorsTool.parameters), }, }, { type: "function" as const, function: { - name: GetVendorByIdTool.name, - description: GetVendorByIdTool.description, - parameters: zodToJsonSchema(GetVendorByIdTool.parameters), + name: GetVendorTool.name, + description: GetVendorTool.description, + parameters: zodToJsonSchema(GetVendorTool.parameters), }, }, { type: "function" as const, function: { - name: GetDocumentsTool.name, - description: GetDocumentsTool.description, - parameters: zodToJsonSchema(GetDocumentsTool.parameters), + name: ListDocumentsTool.name, + description: ListDocumentsTool.description, + parameters: zodToJsonSchema(ListDocumentsTool.parameters), }, }, { type: "function" as const, function: { - name: GetDocumentByIdTool.name, - description: GetDocumentByIdTool.description, - parameters: zodToJsonSchema(GetDocumentByIdTool.parameters), + name: GetDocumentTool.name, + description: GetDocumentTool.description, + parameters: zodToJsonSchema(GetDocumentTool.parameters), }, }, { type: "function" as const, function: { - name: GetDocumentControlsTool.name, - description: GetDocumentControlsTool.description, - parameters: zodToJsonSchema(GetDocumentControlsTool.parameters), + name: ListDocumentControlsTool.name, + description: ListDocumentControlsTool.description, + parameters: zodToJsonSchema(ListDocumentControlsTool.parameters), }, }, { type: "function" as const, function: { - name: GetDocumentLinksTool.name, - description: GetDocumentLinksTool.description, - parameters: zodToJsonSchema(GetDocumentLinksTool.parameters), + name: ListDocumentLinksTool.name, + description: ListDocumentLinksTool.description, + parameters: zodToJsonSchema(ListDocumentLinksTool.parameters), }, }, { type: "function" as const, function: { - name: GetDocumentUploadsTool.name, - description: GetDocumentUploadsTool.description, - parameters: zodToJsonSchema(GetDocumentUploadsTool.parameters), + name: ListDocumentUploadsTool.name, + description: ListDocumentUploadsTool.description, + parameters: zodToJsonSchema(ListDocumentUploadsTool.parameters), }, }, { @@ -248,137 +248,137 @@ const tools = [ { type: "function" as const, function: { - name: GetPoliciesTool.name, - description: GetPoliciesTool.description, - parameters: zodToJsonSchema(GetPoliciesTool.parameters), + name: ListPoliciesTool.name, + description: ListPoliciesTool.description, + parameters: zodToJsonSchema(ListPoliciesTool.parameters), }, }, { type: "function" as const, function: { - name: GetPolicyByIdTool.name, - description: GetPolicyByIdTool.description, - parameters: zodToJsonSchema(GetPolicyByIdTool.parameters), + name: GetPolicyTool.name, + description: GetPolicyTool.description, + parameters: zodToJsonSchema(GetPolicyTool.parameters), }, }, { type: "function" as const, function: { - name: GetDiscoveredVendorsTool.name, - description: GetDiscoveredVendorsTool.description, - parameters: zodToJsonSchema(GetDiscoveredVendorsTool.parameters), + name: ListDiscoveredVendorsTool.name, + description: ListDiscoveredVendorsTool.description, + parameters: zodToJsonSchema(ListDiscoveredVendorsTool.parameters), }, }, { type: "function" as const, function: { - name: GetDiscoveredVendorAccountsTool.name, - description: GetDiscoveredVendorAccountsTool.description, - parameters: zodToJsonSchema(GetDiscoveredVendorAccountsTool.parameters), + name: ListDiscoveredVendorAccountsTool.name, + description: ListDiscoveredVendorAccountsTool.description, + parameters: zodToJsonSchema(ListDiscoveredVendorAccountsTool.parameters), }, }, { type: "function" as const, function: { - name: GetGroupsTool.name, - description: GetGroupsTool.description, - parameters: zodToJsonSchema(GetGroupsTool.parameters), + name: ListGroupsTool.name, + description: ListGroupsTool.description, + parameters: zodToJsonSchema(ListGroupsTool.parameters), }, }, { type: "function" as const, function: { - name: GetGroupByIdTool.name, - description: GetGroupByIdTool.description, - parameters: zodToJsonSchema(GetGroupByIdTool.parameters), + name: GetGroupTool.name, + description: GetGroupTool.description, + parameters: zodToJsonSchema(GetGroupTool.parameters), }, }, { type: "function" as const, function: { - name: GetGroupPeopleTool.name, - description: GetGroupPeopleTool.description, - parameters: zodToJsonSchema(GetGroupPeopleTool.parameters), + name: ListGroupPeopleTool.name, + description: ListGroupPeopleTool.description, + parameters: zodToJsonSchema(ListGroupPeopleTool.parameters), }, }, { type: "function" as const, function: { - name: GetPeopleTool.name, - description: GetPeopleTool.description, - parameters: zodToJsonSchema(GetPeopleTool.parameters), + name: ListPeopleTool.name, + description: ListPeopleTool.description, + parameters: zodToJsonSchema(ListPeopleTool.parameters), }, }, { type: "function" as const, function: { - name: GetPersonByIdTool.name, - description: GetPersonByIdTool.description, - parameters: zodToJsonSchema(GetPersonByIdTool.parameters), + name: GetPersonTool.name, + description: GetPersonTool.description, + parameters: zodToJsonSchema(GetPersonTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerabilitiesTool.name, - description: GetVulnerabilitiesTool.description, - parameters: zodToJsonSchema(GetVulnerabilitiesTool.parameters), + name: ListVulnerabilitiesTool.name, + description: ListVulnerabilitiesTool.description, + parameters: zodToJsonSchema(ListVulnerabilitiesTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerabilityByIdTool.name, - description: GetVulnerabilityByIdTool.description, - parameters: zodToJsonSchema(GetVulnerabilityByIdTool.parameters), + name: GetVulnerabilityTool.name, + description: GetVulnerabilityTool.description, + parameters: zodToJsonSchema(GetVulnerabilityTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerabilityRemediationsTool.name, - description: GetVulnerabilityRemediationsTool.description, - parameters: zodToJsonSchema(GetVulnerabilityRemediationsTool.parameters), + name: ListVulnerabilityRemediationsTool.name, + description: ListVulnerabilityRemediationsTool.description, + parameters: zodToJsonSchema(ListVulnerabilityRemediationsTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerableAssetsTool.name, - description: GetVulnerableAssetsTool.description, - parameters: zodToJsonSchema(GetVulnerableAssetsTool.parameters), + name: ListVulnerableAssetsTool.name, + description: ListVulnerableAssetsTool.description, + parameters: zodToJsonSchema(ListVulnerableAssetsTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerableAssetByIdTool.name, - description: GetVulnerableAssetByIdTool.description, - parameters: zodToJsonSchema(GetVulnerableAssetByIdTool.parameters), + name: GetVulnerableAssetTool.name, + description: GetVulnerableAssetTool.description, + parameters: zodToJsonSchema(GetVulnerableAssetTool.parameters), }, }, { type: "function" as const, function: { - name: GetMonitoredComputersTool.name, - description: GetMonitoredComputersTool.description, - parameters: zodToJsonSchema(GetMonitoredComputersTool.parameters), + name: ListMonitoredComputersTool.name, + description: ListMonitoredComputersTool.description, + parameters: zodToJsonSchema(ListMonitoredComputersTool.parameters), }, }, { type: "function" as const, function: { - name: GetMonitoredComputerByIdTool.name, - description: GetMonitoredComputerByIdTool.description, - parameters: zodToJsonSchema(GetMonitoredComputerByIdTool.parameters), + name: GetMonitoredComputerTool.name, + description: GetMonitoredComputerTool.description, + parameters: zodToJsonSchema(GetMonitoredComputerTool.parameters), }, }, { type: "function" as const, function: { - name: GetVendorRiskAttributesTool.name, - description: GetVendorRiskAttributesTool.description, - parameters: zodToJsonSchema(GetVendorRiskAttributesTool.parameters), + name: ListVendorRiskAttributesTool.name, + description: ListVendorRiskAttributesTool.description, + parameters: zodToJsonSchema(ListVendorRiskAttributesTool.parameters), }, }, { @@ -392,9 +392,9 @@ const tools = [ { type: "function" as const, function: { - name: GetTrustCenterAccessRequestsTool.name, - description: GetTrustCenterAccessRequestsTool.description, - parameters: zodToJsonSchema(GetTrustCenterAccessRequestsTool.parameters), + name: ListTrustCenterAccessRequestsTool.name, + description: ListTrustCenterAccessRequestsTool.description, + parameters: zodToJsonSchema(ListTrustCenterAccessRequestsTool.parameters), }, }, { @@ -408,20 +408,20 @@ const tools = [ { type: "function" as const, function: { - name: GetTrustCenterViewerActivityEventsTool.name, - description: GetTrustCenterViewerActivityEventsTool.description, + name: ListTrustCenterViewerActivityEventsTool.name, + description: ListTrustCenterViewerActivityEventsTool.description, parameters: zodToJsonSchema( - GetTrustCenterViewerActivityEventsTool.parameters, + ListTrustCenterViewerActivityEventsTool.parameters, ), }, }, { type: "function" as const, function: { - name: GetTrustCenterControlCategoriesTool.name, - description: GetTrustCenterControlCategoriesTool.description, + name: ListTrustCenterControlCategoriesTool.name, + description: ListTrustCenterControlCategoriesTool.description, parameters: zodToJsonSchema( - GetTrustCenterControlCategoriesTool.parameters, + ListTrustCenterControlCategoriesTool.parameters, ), }, }, @@ -436,9 +436,9 @@ const tools = [ { type: "function" as const, function: { - name: GetTrustCenterControlsTool.name, - description: GetTrustCenterControlsTool.description, - parameters: zodToJsonSchema(GetTrustCenterControlsTool.parameters), + name: ListTrustCenterControlsTool.name, + description: ListTrustCenterControlsTool.description, + parameters: zodToJsonSchema(ListTrustCenterControlsTool.parameters), }, }, { @@ -452,9 +452,9 @@ const tools = [ { type: "function" as const, function: { - name: GetTrustCenterFaqsTool.name, - description: GetTrustCenterFaqsTool.description, - parameters: zodToJsonSchema(GetTrustCenterFaqsTool.parameters), + name: ListTrustCenterFaqsTool.name, + description: ListTrustCenterFaqsTool.description, + parameters: zodToJsonSchema(ListTrustCenterFaqsTool.parameters), }, }, { @@ -468,9 +468,9 @@ const tools = [ { type: "function" as const, function: { - name: GetTrustCenterResourcesTool.name, - description: GetTrustCenterResourcesTool.description, - parameters: zodToJsonSchema(GetTrustCenterResourcesTool.parameters), + name: ListTrustCenterResourcesTool.name, + description: ListTrustCenterResourcesTool.description, + parameters: zodToJsonSchema(ListTrustCenterResourcesTool.parameters), }, }, { @@ -792,7 +792,7 @@ const testCases: TestCase[] = [ }, { prompt: "List all pending access requests for our Trust Center.", - expectedTool: "get_trust_center_access_requests", + expectedTool: "list_trust_center_access_requests", expectedParams: { slugId: "our-trust-center" }, description: "Should call get_trust_center_access_requests to review access requests", @@ -806,14 +806,14 @@ const testCases: TestCase[] = [ }, { prompt: "What viewer activity has occurred on our Trust Center this month?", - expectedTool: "get_trust_center_viewer_activity_events", + expectedTool: "list_trust_center_viewer_activity_events", expectedParams: { slugId: "our-trust-center" }, description: "Should call get_trust_center_viewer_activity_events to track engagement analytics", }, { prompt: "Show me all the control categories in our Trust Center.", - expectedTool: "get_trust_center_control_categories", + expectedTool: "list_trust_center_control_categories", expectedParams: { slugId: "trust-center" }, description: "Should call get_trust_center_control_categories to list control organization", @@ -827,7 +827,7 @@ const testCases: TestCase[] = [ }, { prompt: "List all the controls published in our public Trust Center.", - expectedTool: "get_trust_center_controls", + expectedTool: "list_trust_center_controls", expectedParams: { slugId: "public-trust-center" }, description: "Should call get_trust_center_controls to see published compliance controls", @@ -844,7 +844,7 @@ const testCases: TestCase[] = [ }, { prompt: "What FAQs are available on our Trust Center for customers?", - expectedTool: "get_trust_center_faqs", + expectedTool: "list_trust_center_faqs", expectedParams: { slugId: "customer-trust-center" }, description: "Should call get_trust_center_faqs to list customer information", @@ -858,7 +858,7 @@ const testCases: TestCase[] = [ { prompt: "What compliance documents and resources are available for download on our Trust Center?", - expectedTool: "get_trust_center_resources", + expectedTool: "list_trust_center_resources", expectedParams: { slugId: "compliance-center" }, description: "Should call get_trust_center_resources to list downloadable materials", diff --git a/src/index.ts b/src/index.ts index fc2c3a2..d8527f6 100644 --- a/src/index.ts +++ b/src/index.ts @@ -135,26 +135,26 @@ import { import { getTrustCenter, GetTrustCenterTool, - getTrustCenterAccessRequests, - GetTrustCenterAccessRequestsTool, + listTrustCenterAccessRequests, + ListTrustCenterAccessRequestsTool, getTrustCenterAccessRequest, GetTrustCenterAccessRequestTool, - getTrustCenterViewerActivityEvents, - GetTrustCenterViewerActivityEventsTool, - getTrustCenterControlCategories, - GetTrustCenterControlCategoriesTool, + listTrustCenterViewerActivityEvents, + ListTrustCenterViewerActivityEventsTool, + listTrustCenterControlCategories, + ListTrustCenterControlCategoriesTool, getTrustCenterControlCategory, GetTrustCenterControlCategoryTool, - getTrustCenterControls, - GetTrustCenterControlsTool, + listTrustCenterControls, + ListTrustCenterControlsTool, getTrustCenterControl, GetTrustCenterControlTool, - getTrustCenterFaqs, - GetTrustCenterFaqsTool, + listTrustCenterFaqs, + ListTrustCenterFaqsTool, getTrustCenterFaq, GetTrustCenterFaqTool, - getTrustCenterResources, - GetTrustCenterResourcesTool, + listTrustCenterResources, + ListTrustCenterResourcesTool, getTrustCenterDocument, GetTrustCenterDocumentTool, } from "./operations/trust-centers.js"; @@ -518,10 +518,10 @@ server.tool( ); server.tool( - GetTrustCenterAccessRequestsTool.name, - GetTrustCenterAccessRequestsTool.description, - GetTrustCenterAccessRequestsTool.parameters.shape, - getTrustCenterAccessRequests, + ListTrustCenterAccessRequestsTool.name, + ListTrustCenterAccessRequestsTool.description, + ListTrustCenterAccessRequestsTool.parameters.shape, + listTrustCenterAccessRequests, ); server.tool( @@ -532,17 +532,17 @@ server.tool( ); server.tool( - GetTrustCenterViewerActivityEventsTool.name, - GetTrustCenterViewerActivityEventsTool.description, - GetTrustCenterViewerActivityEventsTool.parameters.shape, - getTrustCenterViewerActivityEvents, + ListTrustCenterViewerActivityEventsTool.name, + ListTrustCenterViewerActivityEventsTool.description, + ListTrustCenterViewerActivityEventsTool.parameters.shape, + listTrustCenterViewerActivityEvents, ); server.tool( - GetTrustCenterControlCategoriesTool.name, - GetTrustCenterControlCategoriesTool.description, - GetTrustCenterControlCategoriesTool.parameters.shape, - getTrustCenterControlCategories, + ListTrustCenterControlCategoriesTool.name, + ListTrustCenterControlCategoriesTool.description, + ListTrustCenterControlCategoriesTool.parameters.shape, + listTrustCenterControlCategories, ); server.tool( @@ -553,10 +553,10 @@ server.tool( ); server.tool( - GetTrustCenterControlsTool.name, - GetTrustCenterControlsTool.description, - GetTrustCenterControlsTool.parameters.shape, - getTrustCenterControls, + ListTrustCenterControlsTool.name, + ListTrustCenterControlsTool.description, + ListTrustCenterControlsTool.parameters.shape, + listTrustCenterControls, ); server.tool( @@ -567,10 +567,10 @@ server.tool( ); server.tool( - GetTrustCenterFaqsTool.name, - GetTrustCenterFaqsTool.description, - GetTrustCenterFaqsTool.parameters.shape, - getTrustCenterFaqs, + ListTrustCenterFaqsTool.name, + ListTrustCenterFaqsTool.description, + ListTrustCenterFaqsTool.parameters.shape, + listTrustCenterFaqs, ); server.tool( @@ -581,10 +581,10 @@ server.tool( ); server.tool( - GetTrustCenterResourcesTool.name, - GetTrustCenterResourcesTool.description, - GetTrustCenterResourcesTool.parameters.shape, - getTrustCenterResources, + ListTrustCenterResourcesTool.name, + ListTrustCenterResourcesTool.description, + ListTrustCenterResourcesTool.parameters.shape, + listTrustCenterResources, ); server.tool( diff --git a/src/operations/README.md b/src/operations/README.md new file mode 100644 index 0000000..5b392b8 --- /dev/null +++ b/src/operations/README.md @@ -0,0 +1,491 @@ +# Operations Architecture Guide + +This document explains the architecture, patterns, and conventions used in the Vanta MCP Server operations layer. + +## Table of Contents + +- [Overview](#overview) +- [File Structure](#file-structure) +- [Naming Conventions](#naming-conventions) +- [DRY Utilities](#dry-utilities) +- [Schema Factory Functions](#schema-factory-functions) +- [Request Handler Utilities](#request-handler-utilities) +- [Creating New Operations](#creating-new-operations) +- [Best Practices](#best-practices) +- [Examples](#examples) + +## Overview + +The operations layer provides a clean, consistent interface to the Vanta API. Each operation file corresponds to a specific resource type in the Vanta API (e.g., `controls.ts`, `vendors.ts`, `people.ts`). + +### Key Architectural Principles + +1. **DRY (Don't Repeat Yourself)**: Common patterns are abstracted into reusable utilities +2. **RESTful Naming**: Tools follow REST conventions (`list_*` for multiple items, `get_*` for single items) +3. **Type Safety**: Full TypeScript support with proper type definitions +4. **Consistent Error Handling**: Standardized error responses across all operations +5. **Schema Factories**: Reusable Zod schema generators for common patterns + +## File Structure + +``` +operations/ +├── README.md # This file +├── global-descriptions.ts # Centralized parameter descriptions +├── utils.ts # DRY utilities and common functions +├── controls.ts # Control-related operations +├── vendors.ts # Vendor-related operations +├── people.ts # People-related operations +└── ... # Other resource operations +``` + +### Standard Operation File Structure + +Each operation file follows this pattern: + +```typescript +// 1. Imports +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { list of DRY utilities } from "./utils.js"; +import { descriptions } from "./global-descriptions.js"; + +// 2. Input Schemas (using schema factories) +const ListResourcesInput = createPaginationSchema(); +const GetResourceInput = createIdSchema("resourceId", RESOURCE_ID_DESCRIPTION); + +// 3. Tool Definitions +export const ListResourcesTool: Tool = { + name: "list_resources", + description: "...", + parameters: ListResourcesInput, +}; + +// 4. Implementation Functions (using request handlers) +export async function listResources( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/resources", args); +} +``` + +## Naming Conventions + +### REST-Style Tool Names + +- **`list_*`**: Returns multiple items (e.g., `list_controls`, `list_vendors`) +- **`get_*`**: Returns a single item by ID (e.g., `get_control`, `get_vendor`) +- **Special actions**: Keep descriptive names (e.g., `download_document_file`) + +### Consistent Naming Pattern + +```typescript +// ✅ Correct +const ListControlsInput = createPaginationSchema(); +export const ListControlsTool: Tool = { name: "list_controls", ... }; +export async function listControls(args: z.infer): Promise { ... } + +// ✅ Correct +const GetControlInput = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); +export const GetControlTool: Tool = { name: "get_control", ... }; +export async function getControl(args: z.infer): Promise { ... } +``` + +### Function and Constant Naming + +- **Input schemas**: `List*Input`, `Get*Input` +- **Tool exports**: `List*Tool`, `Get*Tool` +- **Implementation functions**: `list*()`, `get*()` + +## DRY Utilities + +The `utils.ts` file provides reusable utilities to eliminate code duplication: + +### Response Processing + +```typescript +// Standard error response +export function createErrorResponse(statusText: string): CallToolResult; + +// Standard success response with JSON +export async function createSuccessResponse( + response: Response, +): Promise; + +// Complete response handling (error or success) +export async function handleApiResponse( + response: Response, +): Promise; +``` + +### URL Construction + +```typescript +// Build URLs with query parameters +export function buildUrl( + basePath: string, + params: Record, +): string; + +// Build resource-by-ID URLs +export function buildResourceUrl(resource: string, id: string): string; +``` + +### Authentication + +```typescript +// Make authenticated requests to Vanta API +export async function makeAuthenticatedRequest( + url: string, + options?: RequestInit, +): Promise; +``` + +## Schema Factory Functions + +Common parameter patterns are abstracted into reusable schema generators: + +### Basic Schemas + +```typescript +// Pagination parameters (pageSize, pageCursor) +const schema = createPaginationSchema(); + +// Single ID parameter +const schema = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); + +// ID + pagination parameters +const schema = createIdWithPaginationSchema("vendorId", VENDOR_ID_DESCRIPTION); + +// Base schema with custom fields +const schema = createFilterSchema({ + categoryMatchesAny: z.array(z.string()).optional(), +}); +``` + +### Extended Schemas + +```typescript +// Extend pagination with custom fields +const ListControlsInput = createPaginationSchema().extend({ + frameworkMatchesAny: z + .array(z.string()) + .describe("Framework IDs to filter by") + .optional(), +}); +``` + +## Request Handler Utilities + +Common request patterns are abstracted into reusable functions: + +### Simple GET Request + +```typescript +export async function listResources( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/resources", args); +} +``` + +### GET by ID + +```typescript +export async function getResource( + args: z.infer, +): Promise { + return makeGetByIdRequest("resources", args.resourceId); +} +``` + +### Custom Endpoints + +```typescript +export async function listResourceDetails( + args: z.infer, +): Promise { + const { resourceId, ...params } = args; + const url = buildUrl(`/v1/resources/${String(resourceId)}/details`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} +``` + +## Creating New Operations + +### Step 1: Create the Operation File + +```typescript +// src/operations/new-resource.ts +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; + +// Define schemas +const ListNewResourcesInput = createPaginationSchema(); +const GetNewResourceInput = createIdSchema( + "newResourceId", + "New resource ID to retrieve", +); + +// Define tools +export const ListNewResourcesTool: Tool = { + name: "list_new_resources", + description: "List all new resources in your Vanta account.", + parameters: ListNewResourcesInput, +}; + +export const GetNewResourceTool: Tool = { + name: "get_new_resource", + description: "Get new resource by ID.", + parameters: GetNewResourceInput, +}; + +// Implement functions +export async function listNewResources( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/new-resources", args); +} + +export async function getNewResource( + args: z.infer, +): Promise { + return makeGetByIdRequest("new-resources", args.newResourceId); +} +``` + +### Step 2: Register in index.ts + +```typescript +// Add imports +import { + ListNewResourcesTool, + GetNewResourceTool, + listNewResources, + getNewResource, +} from "./operations/new-resource.js"; + +// Register tools +server.tool( + ListNewResourcesTool.name, + ListNewResourcesTool.description, + ListNewResourcesTool.parameters.shape, + listNewResources, +); +server.tool( + GetNewResourceTool.name, + GetNewResourceTool.description, + GetNewResourceTool.parameters.shape, + getNewResource, +); +``` + +### Step 3: Add to eval.ts + +```typescript +// Import tools +import { + ListNewResourcesTool, + GetNewResourceTool, +} from "../operations/new-resource.js"; + +// Add to tools array +const tools = [ + // ... existing tools + { + type: "function" as const, + function: { + name: ListNewResourcesTool.name, + description: ListNewResourcesTool.description, + parameters: zodToJsonSchema(ListNewResourcesTool.parameters), + }, + }, + // Add test cases... +]; +``` + +### Step 4: Update README.md + +Add the new operations to the main project README.md. + +## Best Practices + +### 1. Use DRY Utilities + +```typescript +// ✅ Good - Uses DRY utilities +export async function listControls( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/controls", args); +} + +// ❌ Bad - Manual implementation +export async function listControls( + args: z.infer, +): Promise { + const url = new URL("/v1/controls", baseApiUrl()); + if (args.pageSize) + url.searchParams.append("pageSize", args.pageSize.toString()); + // ... 20+ more lines of boilerplate +} +``` + +### 2. Use Schema Factories + +```typescript +// ✅ Good - Uses schema factory +const GetControlInput = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); + +// ❌ Bad - Manual schema +const GetControlInput = z.object({ + controlId: z.string().describe("Control ID to retrieve, e.g. 'control-123'"), +}); +``` + +### 3. Centralize Descriptions + +```typescript +// ✅ Good - Uses centralized description +import { CONTROL_ID_DESCRIPTION } from "./global-descriptions.js"; +const schema = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); + +// ❌ Bad - Hardcoded description +const schema = createIdSchema("controlId", "Control ID to retrieve"); +``` + +### 4. Consistent Error Handling + +```typescript +// ✅ Good - Uses standard response handling +const response = await makeAuthenticatedRequest(url); +return handleApiResponse(response); + +// ❌ Bad - Manual error handling +if (!response.ok) { + return { content: [{ type: "text", text: `Error: ${response.statusText}` }] }; +} +return { + content: [{ type: "text", text: JSON.stringify(await response.json()) }], +}; +``` + +### 5. Type Safety + +```typescript +// ✅ Good - Explicit return type +export async function listControls( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/controls", args); +} + +// ❌ Bad - Missing return type +export async function listControls(args: z.infer) { + return makePaginatedGetRequest("/v1/controls", args); +} +``` + +## Examples + +### Basic List Operation + +```typescript +const ListVendorsInput = createPaginationSchema(); + +export const ListVendorsTool: Tool = { + name: "list_vendors", + description: "List all vendors in your Vanta account.", + parameters: ListVendorsInput, +}; + +export async function listVendors( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/vendors", args); +} +``` + +### Get by ID Operation + +```typescript +const GetVendorInput = createIdSchema("vendorId", VENDOR_ID_DESCRIPTION); + +export const GetVendorTool: Tool = { + name: "get_vendor", + description: "Get vendor by ID.", + parameters: GetVendorInput, +}; + +export async function getVendor( + args: z.infer, +): Promise { + return makeGetByIdRequest("vendors", args.vendorId); +} +``` + +### Custom Filtered List + +```typescript +const ListControlsInput = createPaginationSchema().extend({ + frameworkMatchesAny: z + .array(z.string()) + .describe("Framework IDs to filter by") + .optional(), +}); + +export async function listControls( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/controls", args); +} +``` + +### Nested Resource Operations + +```typescript +const ListVendorDocumentsInput = createIdWithPaginationSchema( + "vendorId", + VENDOR_ID_DESCRIPTION, +); + +export async function listVendorDocuments( + args: z.infer, +): Promise { + const { vendorId, ...params } = args; + const url = buildUrl(`/v1/vendors/${String(vendorId)}/documents`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} +``` + +## Code Quality + +### ESLint Compliance + +- All operation files should pass ESLint with zero errors +- Use `npx eslint src/operations/*.ts --quiet` to check + +### Type Safety + +- All functions must have explicit return types +- Use proper TypeScript types throughout +- Avoid `any` types + +### Testing + +- Add evaluation test cases for all new tools in `eval.ts` +- Update `eval/README.md` with new test descriptions + +--- + +This architecture provides a maintainable, consistent foundation for extending the Vanta MCP Server with new operations while ensuring code quality and developer productivity. diff --git a/src/operations/controls.ts b/src/operations/controls.ts index 1d7e0dd..ecbe481 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -1,17 +1,21 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, - CONTROL_ID_DESCRIPTION, -} from "./global-descriptions.js"; - -const ListControlsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + createPaginationSchema, + createIdSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; +import { CONTROL_ID_DESCRIPTION } from "./global-descriptions.js"; + +// 2. Input Schemas +const ListControlsInput = createPaginationSchema().extend({ frameworkMatchesAny: z .array(z.string()) .describe( @@ -20,6 +24,24 @@ const ListControlsInput = z.object({ .optional(), }); +const ListControlTestsInput = createIdWithPaginationSchema({ + paramName: "controlId", + description: CONTROL_ID_DESCRIPTION, +}); + +const ListLibraryControlsInput = createPaginationSchema(); + +const ListControlDocumentsInput = createIdWithPaginationSchema({ + paramName: "controlId", + description: CONTROL_ID_DESCRIPTION, +}); + +const GetControlInput = createIdSchema({ + paramName: "controlId", + description: CONTROL_ID_DESCRIPTION, +}); + +// 3. Tool Definitions export const ListControlsTool: Tool = { name: "list_controls", description: @@ -27,12 +49,6 @@ export const ListControlsTool: Tool = { parameters: ListControlsInput, }; -const ListControlTestsInput = z.object({ - controlId: z.string().describe(CONTROL_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListControlTestsTool: Tool = { name: "list_control_tests", description: @@ -40,11 +56,6 @@ export const ListControlTestsTool: Tool = { parameters: ListControlTestsInput, }; -const ListLibraryControlsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListLibraryControlsTool: Tool = { name: "list_library_controls", description: @@ -52,22 +63,13 @@ export const ListLibraryControlsTool: Tool = { parameters: ListLibraryControlsInput, }; -const ListControlDocumentsInput = z.object({ - controlId: z.string().describe(CONTROL_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const ListControlDocumentsTool: Tool = { - name: "list_control_documents", - description: - "List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence.", - parameters: ListControlDocumentsInput, -}; - -const GetControlInput = z.object({ - controlId: z.string().describe(CONTROL_ID_DESCRIPTION), -}); +export const ListControlDocumentsTool: Tool = + { + name: "list_control_documents", + description: + "List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence.", + parameters: ListControlDocumentsInput, + }; export const GetControlTool: Tool = { name: "get_control", @@ -76,160 +78,39 @@ export const GetControlTool: Tool = { parameters: GetControlInput, }; +// 4. Implementation Functions export async function listControls( args: z.infer, ): Promise { - const url = new URL("/v1/controls", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - if (args.frameworkMatchesAny !== undefined) { - args.frameworkMatchesAny.forEach(framework => { - url.searchParams.append("frameworkMatchesAny", framework); - }); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/controls", args); } export async function listControlTests( args: z.infer, ): Promise { - const url = new URL(`/v1/controls/${args.controlId}/tests`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { controlId, ...params } = args; + const url = buildUrl(`/v1/controls/${String(controlId)}/tests`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listLibraryControls( args: z.infer, ): Promise { - const url = new URL("/v1/controls/controls-library", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/controls/controls-library", args); } export async function listControlDocuments( args: z.infer, ): Promise { - const url = new URL(`/v1/controls/${args.controlId}/documents`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { controlId, ...params } = args; + const url = buildUrl(`/v1/controls/${String(controlId)}/documents`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getControl( args: z.infer, ): Promise { - const url = new URL(`/v1/controls/${args.controlId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/controls", args.controlId); } diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts index 7ca039c..ca547b6 100644 --- a/src/operations/discovered-vendors.ts +++ b/src/operations/discovered-vendors.ts @@ -1,100 +1,59 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; - -const ListDiscoveredVendorsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + createPaginationSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; + +// 2. Input Schemas +const ListDiscoveredVendorsInput = createPaginationSchema(); + +const ListDiscoveredVendorAccountsInput = createIdWithPaginationSchema({ + paramName: "discoveredVendorId", + description: + "Discovered vendor ID to get accounts for, e.g. 'discovered-vendor-123' or specific discovered vendor identifier", }); -export const ListDiscoveredVendorsTool: Tool = - { - name: "list_discovered_vendors", - description: - "List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding.", - parameters: ListDiscoveredVendorsInput, - }; - -const ListDiscoveredVendorAccountsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); +// 3. Tool Definitions +export const ListDiscoveredVendorsTool: Tool< + typeof ListDiscoveredVendorsInput +> = { + name: "list_discovered_vendors", + description: + "List all discovered vendors in your Vanta account. Returns vendor IDs, names, and metadata for vendor risk management. Use this to see all vendors that have been discovered through automatic detection or manual entry.", + parameters: ListDiscoveredVendorsInput, +}; export const ListDiscoveredVendorAccountsTool: Tool< typeof ListDiscoveredVendorAccountsInput > = { name: "list_discovered_vendor_accounts", description: - "List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors.", + "List a discovered vendor's accounts. Get all accounts associated with a specific discovered vendor for vendor risk management. Use this when you know a discovered vendor ID and want to see which accounts are linked to that vendor.", parameters: ListDiscoveredVendorAccountsInput, }; +// 4. Implementation Functions export async function listDiscoveredVendors( args: z.infer, ): Promise { - const url = new URL("/v1/discovered-vendors", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/discovered-vendors", args); } export async function listDiscoveredVendorAccounts( args: z.infer, ): Promise { - const url = new URL("/v1/discovered-vendors/accounts", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { discoveredVendorId, ...params } = args; + const url = buildUrl( + `/v1/discovered-vendors/${String(discoveredVendorId)}/accounts`, + params, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } diff --git a/src/operations/documents.ts b/src/operations/documents.ts index a087c2a..5ddb144 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -1,19 +1,52 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, - DOCUMENT_ID_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; +import { DOCUMENT_ID_DESCRIPTION } from "./global-descriptions.js"; + +// 2. Input Schemas +const ListDocumentsInput = createPaginationSchema(); + +const GetDocumentInput = createIdSchema({ + paramName: "documentId", + description: DOCUMENT_ID_DESCRIPTION, +}); + +const ListDocumentControlsInput = createIdWithPaginationSchema({ + paramName: "documentId", + description: DOCUMENT_ID_DESCRIPTION, +}); -const ListDocumentsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +const ListDocumentLinksInput = createIdWithPaginationSchema({ + paramName: "documentId", + description: DOCUMENT_ID_DESCRIPTION, }); +const ListDocumentUploadsInput = createIdWithPaginationSchema({ + paramName: "documentId", + description: DOCUMENT_ID_DESCRIPTION, +}); + +const DownloadDocumentFileInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + uploadedFileId: z + .string() + .describe( + "Uploaded file ID to download, e.g. 'file-456' or specific uploaded file identifier", + ), +}); + +// 3. Tool Definitions export const ListDocumentsTool: Tool = { name: "list_documents", description: @@ -21,10 +54,6 @@ export const ListDocumentsTool: Tool = { parameters: ListDocumentsInput, }; -const GetDocumentInput = z.object({ - documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), -}); - export const GetDocumentTool: Tool = { name: "get_document", description: @@ -32,24 +61,13 @@ export const GetDocumentTool: Tool = { parameters: GetDocumentInput, }; -const ListDocumentControlsInput = z.object({ - documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const ListDocumentControlsTool: Tool = { - name: "list_document_controls", - description: - "List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence.", - parameters: ListDocumentControlsInput, -}; - -const ListDocumentLinksInput = z.object({ - documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); +export const ListDocumentControlsTool: Tool = + { + name: "list_document_controls", + description: + "List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence.", + parameters: ListDocumentControlsInput, + }; export const ListDocumentLinksTool: Tool = { name: "list_document_links", @@ -58,12 +76,6 @@ export const ListDocumentLinksTool: Tool = { parameters: ListDocumentLinksInput, }; -const ListDocumentUploadsInput = z.object({ - documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListDocumentUploadsTool: Tool = { name: "list_document_uploads", description: @@ -71,15 +83,6 @@ export const ListDocumentUploadsTool: Tool = { parameters: ListDocumentUploadsInput, }; -const DownloadDocumentFileInput = z.object({ - documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), - uploadedFileId: z - .string() - .describe( - "Uploaded file ID to download, e.g. 'file-456' or specific uploaded file identifier", - ), -}); - export const DownloadDocumentFileTool: Tool = { name: "download_document_file", @@ -88,186 +91,61 @@ export const DownloadDocumentFileTool: Tool = parameters: DownloadDocumentFileInput, }; +// 4. Implementation Functions export async function listDocuments( args: z.infer, ): Promise { - const url = new URL("/v1/documents", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/documents", args); } export async function getDocument( args: z.infer, ): Promise { - const url = new URL(`/v1/documents/${args.documentId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/documents", args.documentId); } export async function listDocumentControls( args: z.infer, ): Promise { - const url = new URL( - `/v1/documents/${args.documentId}/controls`, - baseApiUrl(), - ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { documentId, ...params } = args; + const url = buildUrl(`/v1/documents/${String(documentId)}/controls`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listDocumentLinks( args: z.infer, ): Promise { - const url = new URL(`/v1/documents/${args.documentId}/links`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { documentId, ...params } = args; + const url = buildUrl(`/v1/documents/${String(documentId)}/links`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listDocumentUploads( args: z.infer, ): Promise { - const url = new URL(`/v1/documents/${args.documentId}/uploads`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { documentId, ...params } = args; + const url = buildUrl(`/v1/documents/${String(documentId)}/uploads`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function downloadDocumentFile( args: z.infer, ): Promise { - const url = new URL( - `/v1/documents/${args.documentId}/uploads/${args.uploadedFileId}/media`, - baseApiUrl(), + const url = buildUrl( + `/v1/documents/${String(args.documentId)}/uploads/${String(args.uploadedFileId)}/media`, ); - - const response = await makeAuthenticatedRequest(url.toString()); + const response = await makeAuthenticatedRequest(url); if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; + return handleApiResponse(response); } // Get the content type from the response headers const contentType = - response.headers.get("content-type") || "application/octet-stream"; + response.headers.get("content-type") ?? "application/octet-stream"; const contentLength = response.headers.get("content-length"); // Handle text-based MIME types - return content that LLMs can process diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index 8fbbdb1..b49b6a5 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -1,19 +1,33 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, - FRAMEWORK_ID_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; +import { FRAMEWORK_ID_DESCRIPTION } from "./global-descriptions.js"; + +// 2. Input Schemas +const ListFrameworksInput = createPaginationSchema(); + +const ListFrameworkControlsInput = createIdWithPaginationSchema({ + paramName: "frameworkId", + description: FRAMEWORK_ID_DESCRIPTION, +}); -const ListFrameworksInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +const GetFrameworkInput = createIdSchema({ + paramName: "frameworkId", + description: FRAMEWORK_ID_DESCRIPTION, }); +// 3. Tool Definitions export const ListFrameworksTool: Tool = { name: "list_frameworks", description: @@ -21,107 +35,43 @@ export const ListFrameworksTool: Tool = { parameters: ListFrameworksInput, }; -const ListFrameworkControlsInput = z.object({ - frameworkId: z.string().describe(FRAMEWORK_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const ListFrameworkControlsTool: Tool = - { - name: "list_framework_controls", - description: - "Get the detailed CONTROL REQUIREMENTS for a specific framework (requires frameworkId). Use this when you need the specific control details, requirements, and implementation guidance for a known framework like 'soc2' or 'iso27001'. This returns the actual security controls and their descriptions, NOT the framework list. Use list_frameworks first if you need to see available frameworks.", - parameters: ListFrameworkControlsInput, - }; - -const GetFrameworkInput = z.object({ - frameworkId: z.string().describe(FRAMEWORK_ID_DESCRIPTION), -}); +export const ListFrameworkControlsTool: Tool< + typeof ListFrameworkControlsInput +> = { + name: "list_framework_controls", + description: + "Get the detailed CONTROL REQUIREMENTS for a specific framework (requires frameworkId). Use this when you need the specific control details, requirements, and implementation guidance for a known framework like 'soc2' or 'iso27001'. This returns the actual security controls and their descriptions, NOT the framework list. Use list_frameworks first if you need to see available frameworks.", + parameters: ListFrameworkControlsInput, +}; export const GetFrameworkTool: Tool = { name: "get_framework", description: - "Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state.", + "Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including description, requirements, completion status, and associated controls.", parameters: GetFrameworkInput, }; +// 4. Implementation Functions export async function listFrameworkControls( args: z.infer, ): Promise { - const url = new URL( - `/v1/frameworks/${args.frameworkId}/controls`, - baseApiUrl(), + const { frameworkId, ...params } = args; + const url = buildUrl( + `/v1/frameworks/${String(frameworkId)}/controls`, + params, ); - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - if (!response.ok) { - return { - content: [ - { type: "text" as const, text: `Error: ${response.statusText}` }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listFrameworks( args: z.infer, ): Promise { - const url = new URL("/v1/frameworks", baseApiUrl()); - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { type: "text" as const, text: `Error: ${response.statusText}` }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/frameworks", args); } export async function getFramework( args: z.infer, ): Promise { - const url = new URL(`/v1/frameworks/${args.frameworkId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { type: "text" as const, text: `Error: ${response.statusText}` }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/frameworks", args.frameworkId); } diff --git a/src/operations/groups.ts b/src/operations/groups.ts index 641e5f5..5abf0b3 100644 --- a/src/operations/groups.ts +++ b/src/operations/groups.ts @@ -1,142 +1,73 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; + +// 2. Input Schemas +const ListGroupsInput = createPaginationSchema(); + +const GetGroupInput = createIdSchema({ + paramName: "groupId", + description: + "Group ID to retrieve, e.g. 'group-123' or specific group identifier", +}); -const ListGroupsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +const ListGroupPeopleInput = createIdWithPaginationSchema({ + paramName: "groupId", + description: + "Group ID to get people for, e.g. 'group-123' or specific group identifier", }); +// 3. Tool Definitions export const ListGroupsTool: Tool = { name: "list_groups", description: - "List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control.", + "List all groups in your Vanta account. Returns group IDs, names, descriptions, and member counts for organizational structure management. Use this to see all available groups for access control and compliance.", parameters: ListGroupsInput, }; -const GetGroupInput = z.object({ - groupId: z - .string() - .describe( - "Group ID to retrieve, e.g. 'group-123' or specific group identifier", - ), -}); - export const GetGroupTool: Tool = { name: "get_group", description: - "Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from get_groups response. Returns complete group details including name, description, member count, and access permissions.", + "Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from list_groups response. Returns complete group details including name, description, member list, and access permissions.", parameters: GetGroupInput, }; -const ListGroupPeopleInput = z.object({ - groupId: z - .string() - .describe( - "Group ID to get people for, e.g. 'group-123' or specific group identifier", - ), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListGroupPeopleTool: Tool = { name: "list_group_people", description: - "List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions.", + "List people in a group. Get all people who are members of a specific group for access management and organizational oversight. Returns person details including names, emails, and roles within the group.", parameters: ListGroupPeopleInput, }; +// 4. Implementation Functions export async function listGroups( args: z.infer, ): Promise { - const url = new URL("/v1/groups", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/groups", args); } export async function getGroup( args: z.infer, ): Promise { - const url = new URL(`/v1/groups/${args.groupId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/groups", args.groupId); } export async function listGroupPeople( args: z.infer, ): Promise { - const url = new URL(`/v1/groups/${args.groupId}/people`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { groupId, ...params } = args; + const url = buildUrl(`/v1/groups/${String(groupId)}/people`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index d66ef97..cca7471 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -1,19 +1,65 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, - INTEGRATION_ID_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; +import { INTEGRATION_ID_DESCRIPTION } from "./global-descriptions.js"; + +// 2. Input Schemas +const ListIntegrationsInput = createPaginationSchema(); + +const GetIntegrationInput = createIdSchema({ + paramName: "integrationId", + description: INTEGRATION_ID_DESCRIPTION, +}); -const ListIntegrationsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +const ListIntegrationResourceKindsInput = z.object({ + integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), + ...createPaginationSchema().shape, }); +const GetIntegrationResourceKindDetailsInput = z.object({ + integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), + resourceKind: z + .string() + .describe( + "Resource kind to get details for, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + ), +}); + +const ListIntegrationResourcesInput = z.object({ + integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), + resourceKind: z + .string() + .describe( + "Resource kind to list resources for, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + ), + ...createPaginationSchema().shape, +}); + +const GetIntegrationResourceInput = z.object({ + integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), + resourceKind: z + .string() + .describe( + "Resource kind to get resource from, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + ), + resourceId: z + .string() + .describe( + "Resource ID to get details for, e.g. 'i-1234567890abcdef0', 'bucket-name'", + ), +}); + +// 3. Tool Definitions export const ListIntegrationsTool: Tool = { name: "list_integrations", description: @@ -21,10 +67,6 @@ export const ListIntegrationsTool: Tool = { parameters: ListIntegrationsInput, }; -const GetIntegrationInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), -}); - export const GetIntegrationTool: Tool = { name: "get_integration", description: @@ -32,12 +74,6 @@ export const GetIntegrationTool: Tool = { parameters: GetIntegrationInput, }; -const ListIntegrationResourceKindsInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListIntegrationResourceKindsTool: Tool< typeof ListIntegrationResourceKindsInput > = { @@ -47,15 +83,6 @@ export const ListIntegrationResourceKindsTool: Tool< parameters: ListIntegrationResourceKindsInput, }; -const GetIntegrationResourceKindDetailsInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - resourceKind: z - .string() - .describe( - "Resource kind to get details for, e.g. 'S3Bucket', 'CloudwatchLogGroup'", - ), -}); - export const GetIntegrationResourceKindDetailsTool: Tool< typeof GetIntegrationResourceKindDetailsInput > = { @@ -65,218 +92,77 @@ export const GetIntegrationResourceKindDetailsTool: Tool< parameters: GetIntegrationResourceKindDetailsInput, }; -const GetIntegrationResourcesInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListIntegrationResourcesTool: Tool< typeof ListIntegrationResourcesInput > = { name: "list_integration_resources", description: - "List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration.", + "List resources for a specific resource kind. List all resources of a specific type (kind) discovered by an integration. Use this to see all infrastructure resources of a particular type that Vanta is monitoring through an integration.", parameters: ListIntegrationResourcesInput, }; -const GetIntegrationResourceInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - resourceId: z - .string() - .describe( - "Resource ID to get details for, e.g. 'i-1234567890abcdef0', 'bucket-name'", - ), -}); - export const GetIntegrationResourceTool: Tool< typeof GetIntegrationResourceInput > = { name: "get_integration_resource", description: - "Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration.", + "Get resource by ID within a specific resource kind. Retrieve detailed information about a specific resource of a particular type discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration.", parameters: GetIntegrationResourceInput, }; +// 4. Implementation Functions export async function listIntegrations( args: z.infer, ): Promise { - const url = new URL("/v1/integrations", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/integrations", args); } export async function getIntegration( args: z.infer, ): Promise { - const url = new URL(`/v1/integrations/${args.integrationId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/integrations", args.integrationId); } export async function listIntegrationResourceKinds( args: z.infer, ): Promise { - const url = new URL( - `/v1/integrations/${args.integrationId}/resource-kinds`, - baseApiUrl(), + const { integrationId, ...params } = args; + const url = buildUrl( + `/v1/integrations/${String(integrationId)}/resource-kinds`, + params, ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getIntegrationResourceKindDetails( args: z.infer, ): Promise { - const url = new URL( - `/v1/integrations/${args.integrationId}/resource-kinds/${args.resourceKind}`, - baseApiUrl(), + const url = buildUrl( + `/v1/integrations/${String(args.integrationId)}/resource-kinds/${String(args.resourceKind)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listIntegrationResources( args: z.infer, ): Promise { - const url = new URL( - `/v1/integrations/${args.integrationId}/resources`, - baseApiUrl(), + const { integrationId, resourceKind, ...params } = args; + const url = buildUrl( + `/v1/integrations/${String(integrationId)}/resource-kinds/${String(resourceKind)}/resources`, + params, ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getIntegrationResource( args: z.infer, ): Promise { - const url = new URL( - `/v1/integrations/${args.integrationId}/resources/${args.resourceId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/integrations/${String(args.integrationId)}/resource-kinds/${String(args.resourceKind)}/resources/${String(args.resourceId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts index 349479a..aa2d1de 100644 --- a/src/operations/monitored-computers.ts +++ b/src/operations/monitored-computers.ts @@ -1,100 +1,50 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; -const ListMonitoredComputersInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +// 2. Input Schemas +const ListMonitoredComputersInput = createPaginationSchema(); + +const GetMonitoredComputerInput = createIdSchema({ + paramName: "computerId", + description: + "Computer ID to retrieve, e.g. 'computer-123' or specific computer identifier", }); +// 3. Tool Definitions export const ListMonitoredComputersTool: Tool< typeof ListMonitoredComputersInput > = { name: "list_monitored_computers", description: - "List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization.", + "List all monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and monitoring status for endpoint management. Use this to see all computers being monitored for compliance and security.", parameters: ListMonitoredComputersInput, }; -const GetMonitoredComputerInput = z.object({ - computerId: z - .string() - .describe( - "Computer ID to retrieve, e.g. 'computer-123' or specific computer identifier", - ), -}); - -export const GetMonitoredComputerTool: Tool< - typeof GetMonitoredComputerInput -> = { - name: "get_monitored_computer", - description: - "Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from get_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information.", - parameters: GetMonitoredComputerInput, -}; +export const GetMonitoredComputerTool: Tool = + { + name: "get_monitored_computer", + description: + "Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from list_monitored_computers response. Returns complete computer details including hardware specs, software inventory, and compliance status.", + parameters: GetMonitoredComputerInput, + }; +// 4. Implementation Functions export async function listMonitoredComputers( args: z.infer, ): Promise { - const url = new URL("/v1/monitored-computers", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/monitored-computers", args); } export async function getMonitoredComputer( args: z.infer, ): Promise { - const url = new URL( - `/v1/monitored-computers/${args.computerId}`, - baseApiUrl(), - ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/monitored-computers", args.computerId); } diff --git a/src/operations/people.ts b/src/operations/people.ts index f99c8cb..f9fc5f2 100644 --- a/src/operations/people.ts +++ b/src/operations/people.ts @@ -1,18 +1,24 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; -const ListPeopleInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +// 2. Input Schemas +const ListPeopleInput = createPaginationSchema(); + +const GetPersonInput = createIdSchema({ + paramName: "personId", + description: + "Person ID to retrieve, e.g. 'person-123' or specific person identifier", }); +// 3. Tool Definitions export const ListPeopleTool: Tool = { name: "list_people", description: @@ -20,14 +26,6 @@ export const ListPeopleTool: Tool = { parameters: ListPeopleInput, }; -const GetPersonInput = z.object({ - personId: z - .string() - .describe( - "Person ID to retrieve, e.g. 'person-123' or specific person identifier", - ), -}); - export const GetPersonTool: Tool = { name: "get_person", description: @@ -35,59 +33,15 @@ export const GetPersonTool: Tool = { parameters: GetPersonInput, }; +// 4. Implementation Functions export async function listPeople( args: z.infer, ): Promise { - const url = new URL("/v1/people", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/people", args); } export async function getPerson( args: z.infer, ): Promise { - const url = new URL(`/v1/people/${args.personId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/people", args.personId); } diff --git a/src/operations/policies.ts b/src/operations/policies.ts index 48c218f..561180c 100644 --- a/src/operations/policies.ts +++ b/src/operations/policies.ts @@ -1,18 +1,24 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; -const ListPoliciesInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +// 2. Input Schemas +const ListPoliciesInput = createPaginationSchema(); + +const GetPolicyInput = createIdSchema({ + paramName: "policyId", + description: + "Policy ID to retrieve, e.g. 'policy-123' or specific policy identifier", }); +// 3. Tool Definitions export const ListPoliciesTool: Tool = { name: "list_policies", description: @@ -20,14 +26,6 @@ export const ListPoliciesTool: Tool = { parameters: ListPoliciesInput, }; -const GetPolicyInput = z.object({ - policyId: z - .string() - .describe( - "Policy ID to retrieve, e.g. 'policy-123' or specific policy identifier", - ), -}); - export const GetPolicyTool: Tool = { name: "get_policy", description: @@ -35,59 +33,15 @@ export const GetPolicyTool: Tool = { parameters: GetPolicyInput, }; +// 4. Implementation Functions export async function listPolicies( args: z.infer, ): Promise { - const url = new URL("/v1/policies", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/policies", args); } export async function getPolicy( args: z.infer, ): Promise { - const url = new URL(`/v1/policies/${args.policyId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/policies", args.policyId); } diff --git a/src/operations/risks.ts b/src/operations/risks.ts index 949de74..fd56f28 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -1,16 +1,16 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; - -const ListRisksInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + createFilterSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; + +// 2. Input Schemas +const ListRisksInput = createFilterSchema({ categoryMatchesAny: z .string() .optional() @@ -19,20 +19,19 @@ const ListRisksInput = z.object({ ), }); +const GetRiskInput = createIdSchema({ + paramName: "riskId", + description: + "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier", +}); + +// 3. Tool Definitions export const ListRisksTool: Tool = { name: "list_risks", description: "List all risk scenarios in your Vanta risk register.", parameters: ListRisksInput, }; -const GetRiskInput = z.object({ - riskId: z - .string() - .describe( - "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier", - ), -}); - export const GetRiskTool: Tool = { name: "get_risk", description: @@ -40,55 +39,15 @@ export const GetRiskTool: Tool = { parameters: GetRiskInput, }; +// 4. Implementation Functions export async function listRisks( args: z.infer, ): Promise { - const url = new URL("/v1/risk-scenarios", baseApiUrl()); - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - if (args.categoryMatchesAny !== undefined) { - url.searchParams.append("categoryMatchesAny", args.categoryMatchesAny); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { type: "text" as const, text: `Error: ${response.statusText}` }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/risk-scenarios", args); } export async function getRisk( args: z.infer, ): Promise { - const url = new URL(`/v1/risk-scenarios/${args.riskId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { type: "text" as const, text: `Error: ${response.statusText}` }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/risk-scenarios", args.riskId); } diff --git a/src/operations/tests.ts b/src/operations/tests.ts index eeae3da..af245b4 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -1,176 +1,73 @@ -import { baseApiUrl } from "../api.js"; -import { z } from "zod"; -import { Tool } from "../types.js"; +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { makeAuthenticatedRequest } from "./utils.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; + +// 2. Input Schemas +const ListTestEntitiesInput = createIdWithPaginationSchema({ + paramName: "testId", + description: + "Test ID to get entities for, e.g. 'test-123' or specific test identifier", +}); -export async function listTests( - args: z.infer, -): Promise { - const url = new URL("/v1/tests", baseApiUrl()); +const ListTestsInput = createPaginationSchema(); - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - if (args.statusFilter !== undefined) { - url.searchParams.append("statusFilter", args.statusFilter); - } - if (args.integrationFilter !== undefined) { - url.searchParams.append("integrationFilter", args.integrationFilter); - } - if (args.controlFilter !== undefined) { - url.searchParams.append("controlFilter", args.controlFilter); - } - if (args.frameworkFilter !== undefined) { - url.searchParams.append("frameworkFilter", args.frameworkFilter); - } +const GetTestInput = createIdSchema({ + paramName: "testId", + description: + "Test ID to retrieve, e.g. 'test-123' or specific test identifier", +}); - const response = await makeAuthenticatedRequest(url.toString()); +// 3. Tool Definitions +export const ListTestEntitiesTool: Tool = { + name: "list_test_entities", + description: + "List a test's entities. Get all entities (resources) that are being tested by a specific security test. Use this when you know a test ID and want to see which specific resources (servers, applications, databases, etc.) are being validated for compliance by that test.", + parameters: ListTestEntitiesInput, +}; - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Url: ${url.toString()}, Error: ${response.statusText}`, - }, - ], - }; - } +export const ListTestsTool: Tool = { + name: "list_tests", + description: + "List all security tests configured in your Vanta account. Returns test IDs, names, types, schedules, and current status for compliance monitoring. Use this to see all automated and manual tests running for your security controls.", + parameters: ListTestsInput, +}; - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; -} +export const GetTestTool: Tool = { + name: "get_test", + description: + "Get test by ID. Retrieve detailed information about a specific security test when its ID is known. The ID of a test can be found from list_tests response. Returns complete test details including configuration, execution history, results, and associated controls.", + parameters: GetTestInput, +}; +// 4. Implementation Functions export async function listTestEntities( args: z.infer, ): Promise { - const url = new URL(`/v1/tests/${args.testId}/entities`, baseApiUrl()); - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - if (args.entityStatus !== undefined) { - url.searchParams.append("entityStatus", args.entityStatus); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Url: ${url.toString()}, Error: ${response.statusText}`, - }, - ], - }; - } + const { testId, ...params } = args; + const url = buildUrl(`/v1/tests/${String(testId)}/entities`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; +export async function listTests( + args: z.infer, +): Promise { + return makePaginatedGetRequest("/v1/tests", args); } export async function getTest( args: z.infer, ): Promise { - const url = new URL(`/v1/tests/${args.testId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Url: ${url.toString()}, Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/tests", args.testId); } - -const TOOL_DESCRIPTION = `Retrieve Vanta's automated security and compliance tests. Vanta runs 1,200+ automated tests -continuously to monitor compliance across your infrastructure. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), -cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results -showing which security controls are passing or failing across your infrastructure. Tests that are NOT_APPLICABLE -to your resources are included by default - use statusFilter=NEEDS_ATTENTION to retrieve only actionable failing tests.`; - -const TEST_STATUS_FILTER_DESCRIPTION = `Filter tests by their status. -Helpful for retrieving only relevant or actionable results. -Possible values: OK, DEACTIVATED, NEEDS_ATTENTION, IN_PROGRESS, INVALID, NOT_APPLICABLE.`; - -const INTEGRATION_FILTER_DESCRIPTION = `Filter by integration. Non-exhaustive examples of possible values include aws, azure, gcp, snyk.`; - -const FRAMEWORK_FILTER_DESCRIPTION = `Filter by framework. Non-exhaustive examples: soc2, ccpa, fedramp`; - -const CONTROL_FILTER_DESCRIPTION = `Filter by control. Generally will only be known if pulled from the /v1/controls endpoint.`; - -export const ListTestsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), - statusFilter: z.string().describe(TEST_STATUS_FILTER_DESCRIPTION).optional(), - integrationFilter: z - .string() - .describe(INTEGRATION_FILTER_DESCRIPTION) - .optional(), - frameworkFilter: z.string().describe(FRAMEWORK_FILTER_DESCRIPTION).optional(), - controlFilter: z.string().describe(CONTROL_FILTER_DESCRIPTION).optional(), -}); - -export const ListTestsTool: Tool = { - name: "list_tests", - description: TOOL_DESCRIPTION, - parameters: ListTestsInput, -}; - -const ListTestEntitiesInput = z.object({ - testId: z.string().describe("Lowercase with hyphens"), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), - entityStatus: z - .string() - .describe("Filter by entity status. Possible values: FAILING, DEACTIVATED.") - .optional(), -}); - -export const ListTestEntitiesTool: Tool = { - name: "list_test_entities", - description: `Get the specific failing resources (entities) for a known test ID. Use this when you already - know the test name/ID and need to see which specific infrastructure resources are failing that test. For - example, if you know "aws-security-groups-open-to-world" test is failing, this returns the actual security - group IDs that are failing. Requires a specific testId parameter. Do NOT use this for general test discovery - use list_tests for that.`, - parameters: ListTestEntitiesInput, -}; - -const GetTestInput = z.object({ - testId: z.string().describe("Lowercase with hyphens"), -}); - -export const GetTestTool: Tool = { - name: "get_test", - description: `Get the details of a single specific test when its ID is known. The ID of a test can be - found in the response from list_tests or from the URL of the test in your browser after /tests/.`, - parameters: GetTestInput, -}; diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts index 0f533df..adc31a8 100644 --- a/src/operations/trust-centers.ts +++ b/src/operations/trust-centers.ts @@ -1,18 +1,97 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, - SLUG_ID_DESCRIPTION, -} from "./global-descriptions.js"; + createIdSchema, + createIdWithPaginationSchema, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; +import { SLUG_ID_DESCRIPTION } from "./global-descriptions.js"; + +// 2. Input Schemas +const GetTrustCenterInput = createIdSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const ListTrustCenterAccessRequestsInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const GetTrustCenterAccessRequestInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + accessRequestId: z + .string() + .describe( + "Access request ID to retrieve, e.g. 'request-123' or specific access request identifier", + ), +}); + +const ListTrustCenterViewerActivityEventsInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const ListTrustCenterControlCategoriesInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); -const GetTrustCenterInput = z.object({ +const GetTrustCenterControlCategoryInput = z.object({ slugId: z.string().describe(SLUG_ID_DESCRIPTION), + controlCategoryId: z + .string() + .describe( + "Control category ID to retrieve, e.g. 'category-123' or specific control category identifier", + ), +}); + +const ListTrustCenterControlsInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, }); +const GetTrustCenterControlInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + trustCenterControlId: z + .string() + .describe( + "Trust Center control ID to retrieve, e.g. 'tc-control-123' or specific Trust Center control identifier", + ), +}); + +const ListTrustCenterFaqsInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const GetTrustCenterFaqInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + faqId: z + .string() + .describe("FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier"), +}); + +const ListTrustCenterResourcesInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const GetTrustCenterDocumentInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + resourceId: z + .string() + .describe( + "Trust Center document ID to retrieve, e.g. 'tc-doc-123' or specific Trust Center document identifier", + ), +}); + +// 3. Tool Definitions export const GetTrustCenterTool: Tool = { name: "get_trust_center", description: @@ -20,549 +99,214 @@ export const GetTrustCenterTool: Tool = { parameters: GetTrustCenterInput, }; -const GetTrustCenterAccessRequestsInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const GetTrustCenterAccessRequestsTool: Tool< - typeof GetTrustCenterAccessRequestsInput +export const ListTrustCenterAccessRequestsTool: Tool< + typeof ListTrustCenterAccessRequestsInput > = { - name: "get_trust_center_access_requests", + name: "list_trust_center_access_requests", description: "List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information.", - parameters: GetTrustCenterAccessRequestsInput, + parameters: ListTrustCenterAccessRequestsInput, }; -const GetTrustCenterAccessRequestInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - accessRequestId: z - .string() - .describe( - "Access request ID to retrieve, e.g. 'request-123' or specific access request identifier", - ), -}); - export const GetTrustCenterAccessRequestTool: Tool< typeof GetTrustCenterAccessRequestInput > = { name: "get_trust_center_access_request", description: - "Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions.", + "Get Trust Center access request by ID. Retrieve detailed information about a specific access request to a Trust Center. Use this to review individual access requests including requester details, status, and approval workflow.", parameters: GetTrustCenterAccessRequestInput, }; -const GetTrustCenterViewerActivityEventsInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const GetTrustCenterViewerActivityEventsTool: Tool< - typeof GetTrustCenterViewerActivityEventsInput +export const ListTrustCenterViewerActivityEventsTool: Tool< + typeof ListTrustCenterViewerActivityEventsInput > = { - name: "get_trust_center_viewer_activity_events", + name: "list_trust_center_viewer_activity_events", description: - "List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics.", - parameters: GetTrustCenterViewerActivityEventsInput, + "List Trust Center viewer activity events. Get all viewing and interaction events for a specific Trust Center to understand usage patterns and engagement. Use this for analytics and compliance tracking.", + parameters: ListTrustCenterViewerActivityEventsInput, }; -const GetTrustCenterControlCategoriesInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const GetTrustCenterControlCategoriesTool: Tool< - typeof GetTrustCenterControlCategoriesInput +export const ListTrustCenterControlCategoriesTool: Tool< + typeof ListTrustCenterControlCategoriesInput > = { - name: "get_trust_center_control_categories", + name: "list_trust_center_control_categories", description: - "List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors.", - parameters: GetTrustCenterControlCategoriesInput, + "List Trust Center control categories. Get all available control categories displayed in a specific Trust Center. Use this to understand how compliance controls are organized and presented to your customers.", + parameters: ListTrustCenterControlCategoriesInput, }; -const GetTrustCenterControlCategoryInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - controlCategoryId: z - .string() - .describe( - "Control category ID to retrieve, e.g. 'category-123' or specific control category identifier", - ), -}); - export const GetTrustCenterControlCategoryTool: Tool< typeof GetTrustCenterControlCategoryInput > = { name: "get_trust_center_control_category", description: - "Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management.", + "Get Trust Center control category by ID. Retrieve detailed information about a specific control category in a Trust Center. Use this to get category details, descriptions, and associated controls.", parameters: GetTrustCenterControlCategoryInput, }; -const GetTrustCenterControlsInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const GetTrustCenterControlsTool: Tool< - typeof GetTrustCenterControlsInput +export const ListTrustCenterControlsTool: Tool< + typeof ListTrustCenterControlsInput > = { - name: "get_trust_center_controls", + name: "list_trust_center_controls", description: - "List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors.", - parameters: GetTrustCenterControlsInput, + "List Trust Center controls. Get all compliance controls visible in a specific Trust Center. Use this to see what security controls are publicly displayed to demonstrate your compliance posture.", + parameters: ListTrustCenterControlsInput, }; -const GetTrustCenterControlInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - trustCenterControlId: z - .string() - .describe( - "Trust Center control ID to retrieve, e.g. 'tc-control-123' or specific Trust Center control identifier", - ), -}); - export const GetTrustCenterControlTool: Tool< typeof GetTrustCenterControlInput > = { name: "get_trust_center_control", description: - "Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency.", + "Get Trust Center control by ID. Retrieve detailed information about a specific control displayed in a Trust Center. Use this to get control implementation details, evidence, and public-facing descriptions.", parameters: GetTrustCenterControlInput, }; -const GetTrustCenterFaqsInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const GetTrustCenterFaqsTool: Tool = { - name: "get_trust_center_faqs", +export const ListTrustCenterFaqsTool: Tool = { + name: "list_trust_center_faqs", description: - "List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section.", - parameters: GetTrustCenterFaqsInput, + "List Trust Center FAQs. Get all frequently asked questions published in a specific Trust Center. Use this to review customer-facing compliance and security information.", + parameters: ListTrustCenterFaqsInput, }; -const GetTrustCenterFaqInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - faqId: z - .string() - .describe("FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier"), -}); - export const GetTrustCenterFaqTool: Tool = { name: "get_trust_center_faq", description: - "Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication.", + "Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ item in a Trust Center. Use this to get the full question, answer, and any supporting documentation.", parameters: GetTrustCenterFaqInput, }; -const GetTrustCenterResourcesInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - -export const GetTrustCenterResourcesTool: Tool< - typeof GetTrustCenterResourcesInput +export const ListTrustCenterResourcesTool: Tool< + typeof ListTrustCenterResourcesInput > = { - name: "get_trust_center_resources", + name: "list_trust_center_resources", description: - "List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors.", - parameters: GetTrustCenterResourcesInput, + "List Trust Center resources. Get all downloadable resources and documents available in a specific Trust Center. Use this to see what compliance materials are provided to customers and prospects.", + parameters: ListTrustCenterResourcesInput, }; -const GetTrustCenterDocumentInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - trustCenterDocumentId: z - .string() - .describe( - "Trust Center document ID to retrieve, e.g. 'tc-doc-123' or specific Trust Center document identifier", - ), -}); - export const GetTrustCenterDocumentTool: Tool< typeof GetTrustCenterDocumentInput > = { name: "get_trust_center_document", description: - "Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management.", + "Get Trust Center document by ID. Retrieve detailed information about a specific document available in a Trust Center. Use this to access compliance certifications, policies, and other public-facing documentation.", parameters: GetTrustCenterDocumentInput, }; -// Implementation functions +// 4. Implementation Functions export async function getTrustCenter( args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/trust-centers", args.slugId); } -export async function getTrustCenterAccessRequests( - args: z.infer, +export async function listTrustCenterAccessRequests( + args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/access-requests`, - baseApiUrl(), + const { slugId, ...params } = args; + const url = buildUrl( + `/v1/trust-centers/${String(slugId)}/access-requests`, + params, ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getTrustCenterAccessRequest( args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/access-requests/${args.accessRequestId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/access-requests/${String(args.accessRequestId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } -export async function getTrustCenterViewerActivityEvents( - args: z.infer, +export async function listTrustCenterViewerActivityEvents( + args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/viewer-activity-events`, - baseApiUrl(), - ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { slugId, ...params } = args; + const url = buildUrl(`/v1/trust-centers/${String(slugId)}/activity`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } -export async function getTrustCenterControlCategories( - args: z.infer, +export async function listTrustCenterControlCategories( + args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/control-categories`, - baseApiUrl(), + const { slugId, ...params } = args; + const url = buildUrl( + `/v1/trust-centers/${String(slugId)}/control-categories`, + params, ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getTrustCenterControlCategory( args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/control-categories/${args.controlCategoryId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/control-categories/${String(args.controlCategoryId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } -export async function getTrustCenterControls( - args: z.infer, +export async function listTrustCenterControls( + args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/controls`, - baseApiUrl(), - ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { slugId, ...params } = args; + const url = buildUrl(`/v1/trust-centers/${String(slugId)}/controls`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getTrustCenterControl( args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/controls/${args.trustCenterControlId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/controls/${String(args.trustCenterControlId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } -export async function getTrustCenterFaqs( - args: z.infer, +export async function listTrustCenterFaqs( + args: z.infer, ): Promise { - const url = new URL(`/v1/trust-centers/${args.slugId}/faqs`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { slugId, ...params } = args; + const url = buildUrl(`/v1/trust-centers/${String(slugId)}/faqs`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getTrustCenterFaq( args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/faqs/${args.faqId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/faqs/${String(args.faqId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } -export async function getTrustCenterResources( - args: z.infer, +export async function listTrustCenterResources( + args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/resources`, - baseApiUrl(), - ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { slugId, ...params } = args; + const url = buildUrl(`/v1/trust-centers/${String(slugId)}/resources`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getTrustCenterDocument( args: z.infer, ): Promise { - const url = new URL( - `/v1/trust-centers/${args.slugId}/documents/${args.trustCenterDocumentId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/resources/${String(args.resourceId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } diff --git a/src/operations/utils.ts b/src/operations/utils.ts index c193214..793a91f 100644 --- a/src/operations/utils.ts +++ b/src/operations/utils.ts @@ -1,4 +1,11 @@ import { getValidToken, refreshToken } from "../auth.js"; +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { z } from "zod"; +import { baseApiUrl } from "../api.js"; +import { + PAGE_SIZE_DESCRIPTION, + PAGE_CURSOR_DESCRIPTION, +} from "./global-descriptions.js"; export async function createAuthHeaders(): Promise> { const token = await getValidToken(); @@ -49,3 +56,175 @@ export async function makeAuthenticatedRequest( return response; } + +// ========================================== +// RESPONSE PROCESSING UTILITIES +// ========================================== + +/** + * Creates a standard error response for failed API calls + */ +export function createErrorResponse(statusText: string): CallToolResult { + return { + content: [ + { + type: "text" as const, + text: `Error: ${statusText}`, + }, + ], + }; +} + +/** + * Creates a standard success response with JSON data + */ +export async function createSuccessResponse( + response: Response, +): Promise { + return { + content: [ + { type: "text" as const, text: JSON.stringify(await response.json()) }, + ], + }; +} + +/** + * Handles API response with standard error/success processing + */ +export async function handleApiResponse( + response: Response, +): Promise { + if (!response.ok) { + return createErrorResponse(response.statusText); + } + return createSuccessResponse(response); +} + +// ========================================== +// SCHEMA FACTORY FUNCTIONS +// ========================================== + +/** + * Creates a schema with only pagination parameters + */ +export function createPaginationSchema(): z.ZodObject<{ + pageSize: z.ZodOptional; + pageCursor: z.ZodOptional; +}> { + return z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + }); +} + +/** + * Creates a schema with a single ID parameter + */ +export function createIdSchema(params: { + paramName: string; + description: string; +}): z.ZodObject> { + return z.object({ + [params.paramName]: z.string().describe(params.description), + }); +} + +/** + * Creates a schema with an ID parameter plus pagination + */ +export function createIdWithPaginationSchema(params: { + paramName: string; + description: string; +}): z.ZodObject< + Record< + string, + z.ZodString | z.ZodOptional | z.ZodOptional + > +> { + return z.object({ + [params.paramName]: z.string().describe(params.description), + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + }); +} + +/** + * Creates a base schema that can be extended with custom fields + */ +export function createFilterSchema( + customFields: Record = {}, +): z.ZodObject> { + return z.object({ + pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + ...customFields, + }); +} + +// ========================================== +// URL CONSTRUCTION UTILITIES +// ========================================== + +/** + * Builds a URL with query parameters from an object + */ +export function buildUrl( + basePath: string, + params: Record = {}, +): string { + const url = new URL(basePath, baseApiUrl()); + + Object.entries(params).forEach(([key, value]) => { + if (value !== undefined) { + if (Array.isArray(value)) { + // Handle array parameters (e.g., frameworkMatchesAny) + value.forEach(item => { + url.searchParams.append(key, String(item)); + }); + } else { + url.searchParams.append(key, String(value)); + } + } + }); + + return url.toString(); +} + +// ========================================== +// REQUEST HANDLER UTILITIES +// ========================================== + +/** + * Makes a simple GET request with no parameters + */ +export async function makeSimpleGetRequest( + endpoint: string, +): Promise { + const url = new URL(endpoint, baseApiUrl()); + const response = await makeAuthenticatedRequest(url.toString()); + return handleApiResponse(response); +} + +/** + * Makes a GET request with pagination and filtering parameters + */ +export async function makePaginatedGetRequest( + endpoint: string, + params: Record, +): Promise { + const url = buildUrl(endpoint, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +/** + * Makes a GET request for a specific resource by ID + */ +export async function makeGetByIdRequest( + endpoint: string, + id: string, +): Promise { + const url = buildUrl(`${endpoint}/${String(id)}`); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} diff --git a/src/operations/vendor-risk-attributes.ts b/src/operations/vendor-risk-attributes.ts index d8b6376..02e1be8 100644 --- a/src/operations/vendor-risk-attributes.ts +++ b/src/operations/vendor-risk-attributes.ts @@ -1,55 +1,25 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; -import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; +import { createPaginationSchema, makePaginatedGetRequest } from "./utils.js"; -const ListVendorRiskAttributesInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); +// 2. Input Schemas +const ListVendorRiskAttributesInput = createPaginationSchema(); +// 3. Tool Definitions export const ListVendorRiskAttributesTool: Tool< typeof ListVendorRiskAttributesInput > = { name: "list_vendor_risk_attributes", description: - "List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization.", + "List all vendor risk attributes in your Vanta account. Returns attribute IDs, names, categories, and risk scoring criteria for vendor risk assessment. Use this to see all available risk attributes for evaluating vendor relationships.", parameters: ListVendorRiskAttributesInput, }; +// 4. Implementation Functions export async function listVendorRiskAttributes( args: z.infer, ): Promise { - const url = new URL("/v1/vendor-risk-attributes", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/vendor-risk-attributes", args); } diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index 4c86739..febd632 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -1,19 +1,62 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, - VENDOR_ID_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + createIdWithPaginationSchema, + makePaginatedGetRequest, + makeGetByIdRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./utils.js"; +import { VENDOR_ID_DESCRIPTION } from "./global-descriptions.js"; + +// 2. Input Schemas +const ListVendorsInput = createPaginationSchema(); + +const GetVendorInput = createIdSchema({ + paramName: "vendorId", + description: VENDOR_ID_DESCRIPTION, +}); + +const ListVendorDocumentsInput = createIdWithPaginationSchema({ + paramName: "vendorId", + description: VENDOR_ID_DESCRIPTION, +}); + +const ListVendorFindingsInput = createIdWithPaginationSchema({ + paramName: "vendorId", + description: VENDOR_ID_DESCRIPTION, +}); + +const ListVendorSecurityReviewsInput = createIdWithPaginationSchema({ + paramName: "vendorId", + description: VENDOR_ID_DESCRIPTION, +}); + +const GetVendorSecurityReviewInput = z.object({ + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), + securityReviewId: z + .string() + .describe( + "Security review ID to get details for, e.g. 'security-review-456'", + ), +}); -const ListVendorsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +const ListVendorSecurityReviewDocumentsInput = z.object({ + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), + securityReviewId: z + .string() + .describe( + "Security review ID to get documents for, e.g. 'security-review-456'", + ), + ...createPaginationSchema().shape, }); +// 3. Tool Definitions export const ListVendorsTool: Tool = { name: "list_vendors", description: @@ -21,10 +64,6 @@ export const ListVendorsTool: Tool = { parameters: ListVendorsInput, }; -const GetVendorInput = z.object({ - vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), -}); - export const GetVendorTool: Tool = { name: "get_vendor", description: @@ -32,12 +71,6 @@ export const GetVendorTool: Tool = { parameters: GetVendorInput, }; -const ListVendorDocumentsInput = z.object({ - vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListVendorDocumentsTool: Tool = { name: "list_vendor_documents", description: @@ -45,12 +78,6 @@ export const ListVendorDocumentsTool: Tool = { parameters: ListVendorDocumentsInput, }; -const ListVendorFindingsInput = z.object({ - vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListVendorFindingsTool: Tool = { name: "list_vendor_findings", description: @@ -58,12 +85,6 @@ export const ListVendorFindingsTool: Tool = { parameters: ListVendorFindingsInput, }; -const ListVendorSecurityReviewsInput = z.object({ - vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListVendorSecurityReviewsTool: Tool< typeof ListVendorSecurityReviewsInput > = { @@ -73,15 +94,6 @@ export const ListVendorSecurityReviewsTool: Tool< parameters: ListVendorSecurityReviewsInput, }; -const GetVendorSecurityReviewInput = z.object({ - vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), - securityReviewId: z - .string() - .describe( - "Security review ID to get details for, e.g. 'security-review-456'", - ), -}); - export const GetVendorSecurityReviewTool: Tool< typeof GetVendorSecurityReviewInput > = { @@ -91,17 +103,6 @@ export const GetVendorSecurityReviewTool: Tool< parameters: GetVendorSecurityReviewInput, }; -const ListVendorSecurityReviewDocumentsInput = z.object({ - vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), - securityReviewId: z - .string() - .describe( - "Security review ID to get documents for, e.g. 'security-review-456'", - ), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); - export const ListVendorSecurityReviewDocumentsTool: Tool< typeof ListVendorSecurityReviewDocumentsInput > = { @@ -111,221 +112,67 @@ export const ListVendorSecurityReviewDocumentsTool: Tool< parameters: ListVendorSecurityReviewDocumentsInput, }; +// 4. Implementation Functions export async function listVendors( args: z.infer, ): Promise { - const url = new URL("/v1/vendors", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/vendors", args); } export async function getVendor( args: z.infer, ): Promise { - const url = new URL(`/v1/vendors/${args.vendorId}`, baseApiUrl()); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/vendors", args.vendorId); } export async function listVendorDocuments( args: z.infer, ): Promise { - const url = new URL(`/v1/vendors/${args.vendorId}/documents`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { vendorId, ...params } = args; + const url = buildUrl(`/v1/vendors/${String(vendorId)}/documents`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listVendorFindings( args: z.infer, ): Promise { - const url = new URL(`/v1/vendors/${args.vendorId}/findings`, baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const { vendorId, ...params } = args; + const url = buildUrl(`/v1/vendors/${String(vendorId)}/findings`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listVendorSecurityReviews( args: z.infer, ): Promise { - const url = new URL( - `/v1/vendors/${args.vendorId}/security-reviews`, - baseApiUrl(), + const { vendorId, ...params } = args; + const url = buildUrl( + `/v1/vendors/${String(vendorId)}/security-reviews`, + params, ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function getVendorSecurityReview( args: z.infer, ): Promise { - const url = new URL( - `/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}`, - baseApiUrl(), + const url = buildUrl( + `/v1/vendors/${String(args.vendorId)}/security-reviews/${String(args.securityReviewId)}`, ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listVendorSecurityReviewDocuments( args: z.infer, ): Promise { - const url = new URL( - `/v1/vendors/${args.vendorId}/security-reviews/${args.securityReviewId}/documents`, - baseApiUrl(), + const { vendorId, securityReviewId, ...params } = args; + const url = buildUrl( + `/v1/vendors/${String(vendorId)}/security-reviews/${String(securityReviewId)}/documents`, + params, ); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index 57cec32..d2c46ea 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -1,97 +1,47 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; -const ListVulnerabilitiesInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), +// 2. Input Schemas +const ListVulnerabilitiesInput = createPaginationSchema(); + +const GetVulnerabilityInput = createIdSchema({ + paramName: "vulnerabilityId", + description: + "Vulnerability ID to retrieve, e.g. 'vulnerability-123' or specific vulnerability identifier", }); +// 3. Tool Definitions export const ListVulnerabilitiesTool: Tool = { name: "list_vulnerabilities", description: - "Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications.", + "List all vulnerabilities in your Vanta account. Returns vulnerability IDs, severity levels, affected systems, and remediation status. Use this to see all identified security vulnerabilities for risk management.", parameters: ListVulnerabilitiesInput, }; -const GetVulnerabilityInput = z.object({ - vulnerabilityId: z - .string() - .describe( - "Vulnerability ID to retrieve, e.g. 'vuln-123' or specific vulnerability identifier", - ), -}); - -export const GetVulnerabilityTool: Tool = - { - name: "get_vulnerability", - description: - "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status.", - parameters: GetVulnerabilityInput, - }; +export const GetVulnerabilityTool: Tool = { + name: "get_vulnerability", + description: + "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including description, CVSS scores, affected assets, and remediation guidance.", + parameters: GetVulnerabilityInput, +}; +// 4. Implementation Functions export async function listVulnerabilities( args: z.infer, ): Promise { - const url = new URL("/v1/vulnerabilities", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/vulnerabilities", args); } export async function getVulnerability( args: z.infer, ): Promise { - const url = new URL( - `/v1/vulnerabilities/${args.vulnerabilityId}`, - baseApiUrl(), - ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/vulnerabilities", args.vulnerabilityId); } diff --git a/src/operations/vulnerability-remediations.ts b/src/operations/vulnerability-remediations.ts index 2ce0233..6cafc1d 100644 --- a/src/operations/vulnerability-remediations.ts +++ b/src/operations/vulnerability-remediations.ts @@ -1,55 +1,25 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; -import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; +import { createPaginationSchema, makePaginatedGetRequest } from "./utils.js"; -const ListVulnerabilityRemediationsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); +// 2. Input Schemas +const ListVulnerabilityRemediationsInput = createPaginationSchema(); +// 3. Tool Definitions export const ListVulnerabilityRemediationsTool: Tool< typeof ListVulnerabilityRemediationsInput > = { name: "list_vulnerability_remediations", description: - "List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues.", + "List all vulnerability remediations in your Vanta account. Returns remediation IDs, vulnerability references, status, and progress for tracking security improvements. Use this to see all vulnerability remediation efforts and their current status.", parameters: ListVulnerabilityRemediationsInput, }; +// 4. Implementation Functions export async function listVulnerabilityRemediations( args: z.infer, ): Promise { - const url = new URL("/v1/vulnerability-remediations", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/vulnerability-remediations", args); } diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts index d43001c..bccc7af 100644 --- a/src/operations/vulnerable-assets.ts +++ b/src/operations/vulnerable-assets.ts @@ -1,98 +1,48 @@ +// 1. Imports import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { baseApiUrl } from "../api.js"; import { Tool } from "../types.js"; import { z } from "zod"; -import { makeAuthenticatedRequest } from "./utils.js"; import { - PAGE_SIZE_DESCRIPTION, - PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; -const ListVulnerableAssetsInput = z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), -}); +// 2. Input Schemas +const ListVulnerableAssetsInput = createPaginationSchema(); -export const ListVulnerableAssetsTool: Tool = { - name: "list_vulnerable_assets", +const GetVulnerableAssetInput = createIdSchema({ + paramName: "vulnerableAssetId", description: - "List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts.", - parameters: ListVulnerableAssetsInput, -}; - -const GetVulnerableAssetInput = z.object({ - vulnerableAssetId: z - .string() - .describe( - "Vulnerable asset ID to retrieve, e.g. 'asset-123' or specific vulnerable asset identifier", - ), + "Vulnerable asset ID to retrieve, e.g. 'vulnerable-asset-123' or specific asset identifier", }); -export const GetVulnerableAssetTool: Tool< - typeof GetVulnerableAssetInput -> = { +// 3. Tool Definitions +export const ListVulnerableAssetsTool: Tool = + { + name: "list_vulnerable_assets", + description: + "List all vulnerable assets in your Vanta account. Returns asset IDs, hostnames, vulnerability counts, and risk scores for security monitoring. Use this to see all assets that have identified vulnerabilities requiring attention.", + parameters: ListVulnerableAssetsInput, + }; + +export const GetVulnerableAssetTool: Tool = { name: "get_vulnerable_asset", description: - "Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from get_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status.", + "Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from list_vulnerable_assets response. Returns complete asset details including vulnerability list, risk assessment, and remediation recommendations.", parameters: GetVulnerableAssetInput, }; +// 4. Implementation Functions export async function listVulnerableAssets( args: z.infer, ): Promise { - const url = new URL("/v1/vulnerable-assets", baseApiUrl()); - - if (args.pageSize !== undefined) { - url.searchParams.append("pageSize", args.pageSize.toString()); - } - if (args.pageCursor !== undefined) { - url.searchParams.append("pageCursor", args.pageCursor); - } - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makePaginatedGetRequest("/v1/vulnerable-assets", args); } export async function getVulnerableAsset( args: z.infer, ): Promise { - const url = new URL( - `/v1/vulnerable-assets/${args.vulnerableAssetId}`, - baseApiUrl(), - ); - - const response = await makeAuthenticatedRequest(url.toString()); - - if (!response.ok) { - return { - content: [ - { - type: "text" as const, - text: `Error: ${response.statusText}`, - }, - ], - }; - } - - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + return makeGetByIdRequest("/v1/vulnerable-assets", args.vulnerableAssetId); } From 4d5f46b7adda4dfca5d7f2e0032476a7675b54a0 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Wed, 24 Sep 2025 15:51:38 -0400 Subject: [PATCH 18/24] Add missing Trust Center GET endpoints --- README.md | 40 ++-- src/eval/README.md | 6 +- src/eval/eval.ts | 203 +++++++++++++++++++- src/index.ts | 108 +++++++++++ src/operations/trust-centers.ts | 317 ++++++++++++++++++++++++++++++++ 5 files changed, 656 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 3e41f1f..f30a840 100644 --- a/README.md +++ b/README.md @@ -167,20 +167,32 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Provide downloadable resources including compliance documents and certifications - Enable customer self-service access to compliance and security information -| Tool Name | Description | -| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | -| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | -| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | -| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | -| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | -| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | -| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | -| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | -| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | -| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | -| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | -| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | +| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | +| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | +| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | +| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | +| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | +| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | +| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | +| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | +| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | +| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | +| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | +| [`get_trust_center_resource_media`](https://developer.vanta.com/reference/gettrustcenterresourcemedia) | Download Trust Center document media. Get the actual uploaded document/media file for a Trust Center resource for review or audit purposes. | +| [`list_trust_center_subprocessors`](https://developer.vanta.com/reference/listtrustcentersubprocessors) | List Trust Center subprocessors. Get all subprocessors displayed in a specific Trust Center for third-party service provider transparency. | +| [`get_trust_center_subprocessor`](https://developer.vanta.com/reference/gettrustcentersubprocessor) | Get Trust Center subprocessor by ID. Retrieve detailed information about a specific subprocessor including compliance details and certifications. | +| [`list_trust_center_updates`](https://developer.vanta.com/reference/listtrustcenterupdates) | List Trust Center updates. Get all updates and announcements published in a specific Trust Center for compliance status changes and notifications. | +| [`get_trust_center_update`](https://developer.vanta.com/reference/gettrustcenterupdate) | Get Trust Center update by ID. Retrieve detailed information about a specific update including content, publication date, and compliance impact. | +| [`list_trust_center_viewers`](https://developer.vanta.com/reference/listtrustcenterviewers) | List Trust Center viewers. Get all users who have access to view a specific Trust Center for access management and audit purposes. | +| [`get_trust_center_viewer`](https://developer.vanta.com/reference/gettrustcenterviewer) | Get Trust Center viewer by ID. Retrieve detailed information about a specific viewer including access permissions and activity history. | +| [`get_trust_center_subscriber`](https://developer.vanta.com/reference/gettrustcentersubscriber) | Get Trust Center subscriber by ID. Retrieve detailed information about a specific subscriber including subscription preferences and notification settings. | +| [`get_trust_center_subscriber_group`](https://developer.vanta.com/reference/gettrustcentersubscribergroup) | Get Trust Center subscriber group by ID. Retrieve detailed information about a specific subscriber group including members and notification preferences. | +| [`list_trust_center_subscriber_groups`](https://developer.vanta.com/reference/listtrustcentersubscribergroups) | List Trust Center subscriber groups. Get all subscriber groups configured for a specific Trust Center for notification group management. | +| [`list_trust_center_historical_access_requests`](https://developer.vanta.com/reference/listtrustcenterhistoricalaccessrequests) | List Trust Center historical access requests. Get all past access requests for a specific Trust Center for audit and compliance tracking. | +| [`list_trust_center_subscribers`](https://developer.vanta.com/reference/listtrustcentersubscribers) | List Trust Center subscribers. Get all subscribers to a specific Trust Center for update notifications and communication management. | ### Vendor Risk Attributes diff --git a/src/eval/README.md b/src/eval/README.md index 6fffaf7..f57fa5c 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -40,7 +40,7 @@ OPENAI_API_KEY="your_openai_api_key_here" node build/eval/eval.js ## Test Cases -The evaluation includes 54 test cases covering: +The evaluation includes 66 test cases covering: ### ✅ **Tool Selection Tests** @@ -120,8 +120,8 @@ The evaluation includes 54 test cases covering: 📊 Final Results ================ -✅ Passed: 54/54 tests -❌ Failed: 0/54 tests +✅ Passed: 66/66 tests +❌ Failed: 0/66 tests 📈 Success Rate: 100% 🎉 All tests passed! Tool calling behavior is working correctly. ``` diff --git a/src/eval/eval.ts b/src/eval/eval.ts index dc66868..86aee8a 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -65,6 +65,18 @@ import { GetTrustCenterFaqTool, ListTrustCenterResourcesTool, GetTrustCenterDocumentTool, + GetTrustCenterResourceMediaTool, + ListTrustCenterSubprocessorsTool, + GetTrustCenterSubprocessorTool, + ListTrustCenterUpdatesTool, + GetTrustCenterUpdateTool, + ListTrustCenterViewersTool, + GetTrustCenterViewerTool, + GetTrustCenterSubscriberTool, + GetTrustCenterSubscriberGroupTool, + ListTrustCenterSubscriberGroupsTool, + ListTrustCenterHistoricalAccessRequestsTool, + ListTrustCenterSubscribersTool, } from "../operations/trust-centers.js"; // Format all tools for OpenAI @@ -481,6 +493,106 @@ const tools = [ parameters: zodToJsonSchema(GetTrustCenterDocumentTool.parameters), }, }, + { + type: "function" as const, + function: { + name: GetTrustCenterResourceMediaTool.name, + description: GetTrustCenterResourceMediaTool.description, + parameters: zodToJsonSchema(GetTrustCenterResourceMediaTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: ListTrustCenterSubprocessorsTool.name, + description: ListTrustCenterSubprocessorsTool.description, + parameters: zodToJsonSchema(ListTrustCenterSubprocessorsTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterSubprocessorTool.name, + description: GetTrustCenterSubprocessorTool.description, + parameters: zodToJsonSchema(GetTrustCenterSubprocessorTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: ListTrustCenterUpdatesTool.name, + description: ListTrustCenterUpdatesTool.description, + parameters: zodToJsonSchema(ListTrustCenterUpdatesTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterUpdateTool.name, + description: GetTrustCenterUpdateTool.description, + parameters: zodToJsonSchema(GetTrustCenterUpdateTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: ListTrustCenterViewersTool.name, + description: ListTrustCenterViewersTool.description, + parameters: zodToJsonSchema(ListTrustCenterViewersTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterViewerTool.name, + description: GetTrustCenterViewerTool.description, + parameters: zodToJsonSchema(GetTrustCenterViewerTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterSubscriberTool.name, + description: GetTrustCenterSubscriberTool.description, + parameters: zodToJsonSchema(GetTrustCenterSubscriberTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetTrustCenterSubscriberGroupTool.name, + description: GetTrustCenterSubscriberGroupTool.description, + parameters: zodToJsonSchema(GetTrustCenterSubscriberGroupTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: ListTrustCenterSubscriberGroupsTool.name, + description: ListTrustCenterSubscriberGroupsTool.description, + parameters: zodToJsonSchema( + ListTrustCenterSubscriberGroupsTool.parameters, + ), + }, + }, + { + type: "function" as const, + function: { + name: ListTrustCenterHistoricalAccessRequestsTool.name, + description: ListTrustCenterHistoricalAccessRequestsTool.description, + parameters: zodToJsonSchema( + ListTrustCenterHistoricalAccessRequestsTool.parameters, + ), + }, + }, + { + type: "function" as const, + function: { + name: ListTrustCenterSubscribersTool.name, + description: ListTrustCenterSubscribersTool.description, + parameters: zodToJsonSchema(ListTrustCenterSubscribersTool.parameters), + }, + }, ]; // Test cases with expected tool calls @@ -869,11 +981,100 @@ const testCases: TestCase[] = [ expectedTool: "get_trust_center_document", expectedParams: { slugId: "trust-center", - trustCenterDocumentId: "DOC-456", + resourceId: "DOC-456", }, description: "Should call get_trust_center_document for specific document details", }, + { + prompt: + "Download the actual compliance certificate file CERT-123 from our Trust Center.", + expectedTool: "get_trust_center_resource_media", + expectedParams: { slugId: "trust-center", resourceId: "CERT-123" }, + description: + "Should call get_trust_center_resource_media to download document media", + }, + { + prompt: + "List all subprocessors displayed on our Trust Center for customer transparency.", + expectedTool: "list_trust_center_subprocessors", + expectedParams: { slugId: "customer-trust-center" }, + description: + "Should call list_trust_center_subprocessors to list third-party service providers", + }, + { + prompt: + "Get details about subprocessor SUBPROC-789 listed on our Trust Center.", + expectedTool: "get_trust_center_subprocessor", + expectedParams: { slugId: "trust-center", subprocessorId: "SUBPROC-789" }, + description: + "Should call get_trust_center_subprocessor for specific subprocessor information", + }, + { + prompt: + "Show me all the recent updates and announcements on our Trust Center.", + expectedTool: "list_trust_center_updates", + expectedParams: { slugId: "company-trust-center" }, + description: + "Should call list_trust_center_updates to see compliance notifications", + }, + { + prompt: + "Get the details of Trust Center update UPDATE-456 about SOC2 compliance.", + expectedTool: "get_trust_center_update", + expectedParams: { slugId: "trust-center", updateId: "UPDATE-456" }, + description: + "Should call get_trust_center_update for specific update content", + }, + { + prompt: "Who has access to view our Trust Center? List all viewers.", + expectedTool: "list_trust_center_viewers", + expectedParams: { slugId: "private-trust-center" }, + description: "Should call list_trust_center_viewers for access management", + }, + { + prompt: "Get access details for Trust Center viewer USER-123.", + expectedTool: "get_trust_center_viewer", + expectedParams: { slugId: "trust-center", viewerId: "USER-123" }, + description: + "Should call get_trust_center_viewer for specific viewer information", + }, + { + prompt: "Get notification preferences for Trust Center subscriber SUB-789.", + expectedTool: "get_trust_center_subscriber", + expectedParams: { slugId: "trust-center", subscriberId: "SUB-789" }, + description: + "Should call get_trust_center_subscriber for subscriber settings", + }, + { + prompt: "Show me details about Trust Center subscriber group GROUP-456.", + expectedTool: "get_trust_center_subscriber_group", + expectedParams: { slugId: "trust-center", subscriberGroupId: "GROUP-456" }, + description: + "Should call get_trust_center_subscriber_group for group information", + }, + { + prompt: "List all notification groups configured for our Trust Center.", + expectedTool: "list_trust_center_subscriber_groups", + expectedParams: { slugId: "notification-center" }, + description: + "Should call list_trust_center_subscriber_groups for group management", + }, + { + prompt: + "Show me all historical access requests for our Trust Center from last year.", + expectedTool: "list_trust_center_historical_access_requests", + expectedParams: { slugId: "audit-trust-center" }, + description: + "Should call list_trust_center_historical_access_requests for audit tracking", + }, + { + prompt: "List everyone subscribed to updates from our Trust Center.", + expectedTool: "list_trust_center_subscribers", + expectedParams: { slugId: "update-center" }, + description: + "Should call list_trust_center_subscribers for communication management", + }, { prompt: "What programming tests should I write for my API?", expectedTool: "none", diff --git a/src/index.ts b/src/index.ts index d8527f6..d9f1cac 100644 --- a/src/index.ts +++ b/src/index.ts @@ -157,6 +157,30 @@ import { ListTrustCenterResourcesTool, getTrustCenterDocument, GetTrustCenterDocumentTool, + getTrustCenterResourceMedia, + GetTrustCenterResourceMediaTool, + listTrustCenterSubprocessors, + ListTrustCenterSubprocessorsTool, + getTrustCenterSubprocessor, + GetTrustCenterSubprocessorTool, + listTrustCenterUpdates, + ListTrustCenterUpdatesTool, + getTrustCenterUpdate, + GetTrustCenterUpdateTool, + listTrustCenterViewers, + ListTrustCenterViewersTool, + getTrustCenterViewer, + GetTrustCenterViewerTool, + getTrustCenterSubscriber, + GetTrustCenterSubscriberTool, + getTrustCenterSubscriberGroup, + GetTrustCenterSubscriberGroupTool, + listTrustCenterSubscriberGroups, + ListTrustCenterSubscriberGroupsTool, + listTrustCenterHistoricalAccessRequests, + ListTrustCenterHistoricalAccessRequestsTool, + listTrustCenterSubscribers, + ListTrustCenterSubscribersTool, } from "./operations/trust-centers.js"; import { initializeToken } from "./auth.js"; @@ -594,6 +618,90 @@ server.tool( getTrustCenterDocument, ); +server.tool( + GetTrustCenterResourceMediaTool.name, + GetTrustCenterResourceMediaTool.description, + GetTrustCenterResourceMediaTool.parameters.shape, + getTrustCenterResourceMedia, +); + +server.tool( + ListTrustCenterSubprocessorsTool.name, + ListTrustCenterSubprocessorsTool.description, + ListTrustCenterSubprocessorsTool.parameters.shape, + listTrustCenterSubprocessors, +); + +server.tool( + GetTrustCenterSubprocessorTool.name, + GetTrustCenterSubprocessorTool.description, + GetTrustCenterSubprocessorTool.parameters.shape, + getTrustCenterSubprocessor, +); + +server.tool( + ListTrustCenterUpdatesTool.name, + ListTrustCenterUpdatesTool.description, + ListTrustCenterUpdatesTool.parameters.shape, + listTrustCenterUpdates, +); + +server.tool( + GetTrustCenterUpdateTool.name, + GetTrustCenterUpdateTool.description, + GetTrustCenterUpdateTool.parameters.shape, + getTrustCenterUpdate, +); + +server.tool( + ListTrustCenterViewersTool.name, + ListTrustCenterViewersTool.description, + ListTrustCenterViewersTool.parameters.shape, + listTrustCenterViewers, +); + +server.tool( + GetTrustCenterViewerTool.name, + GetTrustCenterViewerTool.description, + GetTrustCenterViewerTool.parameters.shape, + getTrustCenterViewer, +); + +server.tool( + GetTrustCenterSubscriberTool.name, + GetTrustCenterSubscriberTool.description, + GetTrustCenterSubscriberTool.parameters.shape, + getTrustCenterSubscriber, +); + +server.tool( + GetTrustCenterSubscriberGroupTool.name, + GetTrustCenterSubscriberGroupTool.description, + GetTrustCenterSubscriberGroupTool.parameters.shape, + getTrustCenterSubscriberGroup, +); + +server.tool( + ListTrustCenterSubscriberGroupsTool.name, + ListTrustCenterSubscriberGroupsTool.description, + ListTrustCenterSubscriberGroupsTool.parameters.shape, + listTrustCenterSubscriberGroups, +); + +server.tool( + ListTrustCenterHistoricalAccessRequestsTool.name, + ListTrustCenterHistoricalAccessRequestsTool.description, + ListTrustCenterHistoricalAccessRequestsTool.parameters.shape, + listTrustCenterHistoricalAccessRequests, +); + +server.tool( + ListTrustCenterSubscribersTool.name, + ListTrustCenterSubscribersTool.description, + ListTrustCenterSubscribersTool.parameters.shape, + listTrustCenterSubscribers, +); + async function main() { try { await initializeToken(); diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts index adc31a8..1e6d169 100644 --- a/src/operations/trust-centers.ts +++ b/src/operations/trust-centers.ts @@ -91,6 +91,91 @@ const GetTrustCenterDocumentInput = z.object({ ), }); +const GetTrustCenterResourceMediaInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + resourceId: z + .string() + .describe( + "Trust Center document/resource ID to download media for, e.g. 'tc-doc-123' or specific Trust Center document identifier", + ), +}); + +const ListTrustCenterSubprocessorsInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const GetTrustCenterSubprocessorInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + subprocessorId: z + .string() + .describe( + "Subprocessor ID to retrieve, e.g. 'subprocessor-123' or specific subprocessor identifier", + ), +}); + +const ListTrustCenterUpdatesInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const GetTrustCenterUpdateInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + updateId: z + .string() + .describe( + "Update ID to retrieve, e.g. 'update-123' or specific update identifier", + ), +}); + +const ListTrustCenterViewersInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const GetTrustCenterViewerInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + viewerId: z + .string() + .describe( + "Viewer ID to retrieve, e.g. 'viewer-123' or specific viewer identifier", + ), +}); + +const GetTrustCenterSubscriberInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + subscriberId: z + .string() + .describe( + "Subscriber ID to retrieve, e.g. 'subscriber-123' or specific subscriber identifier", + ), +}); + +const GetTrustCenterSubscriberGroupInput = z.object({ + slugId: z.string().describe(SLUG_ID_DESCRIPTION), + subscriberGroupId: z + .string() + .describe( + "Subscriber group ID to retrieve, e.g. 'group-123' or specific subscriber group identifier", + ), +}); + +const ListTrustCenterSubscriberGroupsInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + +const ListTrustCenterHistoricalAccessRequestsInput = + createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, + }); + +const ListTrustCenterSubscribersInput = createIdWithPaginationSchema({ + paramName: "slugId", + description: SLUG_ID_DESCRIPTION, +}); + // 3. Tool Definitions export const GetTrustCenterTool: Tool = { name: "get_trust_center", @@ -194,6 +279,112 @@ export const GetTrustCenterDocumentTool: Tool< parameters: GetTrustCenterDocumentInput, }; +export const GetTrustCenterResourceMediaTool: Tool< + typeof GetTrustCenterResourceMediaInput +> = { + name: "get_trust_center_resource_media", + description: + "Download Trust Center document media. Get the actual uploaded document/media file for a Trust Center resource. Use this to download compliance documents, certifications, and other materials for review or audit purposes.", + parameters: GetTrustCenterResourceMediaInput, +}; + +export const ListTrustCenterSubprocessorsTool: Tool< + typeof ListTrustCenterSubprocessorsInput +> = { + name: "list_trust_center_subprocessors", + description: + "List Trust Center subprocessors. Get all subprocessors displayed in a specific Trust Center. Use this to see third-party service providers and their compliance information for transparency.", + parameters: ListTrustCenterSubprocessorsInput, +}; + +export const GetTrustCenterSubprocessorTool: Tool< + typeof GetTrustCenterSubprocessorInput +> = { + name: "get_trust_center_subprocessor", + description: + "Get Trust Center subprocessor by ID. Retrieve detailed information about a specific subprocessor including compliance details, certifications, and data processing information.", + parameters: GetTrustCenterSubprocessorInput, +}; + +export const ListTrustCenterUpdatesTool: Tool< + typeof ListTrustCenterUpdatesInput +> = { + name: "list_trust_center_updates", + description: + "List Trust Center updates. Get all updates and announcements published in a specific Trust Center. Use this to see compliance status changes, security updates, and important notifications.", + parameters: ListTrustCenterUpdatesInput, +}; + +export const GetTrustCenterUpdateTool: Tool = + { + name: "get_trust_center_update", + description: + "Get Trust Center update by ID. Retrieve detailed information about a specific update including content, publication date, and impact on compliance status.", + parameters: GetTrustCenterUpdateInput, + }; + +export const ListTrustCenterViewersTool: Tool< + typeof ListTrustCenterViewersInput +> = { + name: "list_trust_center_viewers", + description: + "List Trust Center viewers. Get all users who have access to view a specific Trust Center. Use this for access management and audit purposes.", + parameters: ListTrustCenterViewersInput, +}; + +export const GetTrustCenterViewerTool: Tool = + { + name: "get_trust_center_viewer", + description: + "Get Trust Center viewer by ID. Retrieve detailed information about a specific viewer including access permissions, activity history, and contact information.", + parameters: GetTrustCenterViewerInput, + }; + +export const GetTrustCenterSubscriberTool: Tool< + typeof GetTrustCenterSubscriberInput +> = { + name: "get_trust_center_subscriber", + description: + "Get Trust Center subscriber by ID. Retrieve detailed information about a specific subscriber including subscription preferences and notification settings.", + parameters: GetTrustCenterSubscriberInput, +}; + +export const GetTrustCenterSubscriberGroupTool: Tool< + typeof GetTrustCenterSubscriberGroupInput +> = { + name: "get_trust_center_subscriber_group", + description: + "Get Trust Center subscriber group by ID. Retrieve detailed information about a specific subscriber group including members and notification preferences.", + parameters: GetTrustCenterSubscriberGroupInput, +}; + +export const ListTrustCenterSubscriberGroupsTool: Tool< + typeof ListTrustCenterSubscriberGroupsInput +> = { + name: "list_trust_center_subscriber_groups", + description: + "List Trust Center subscriber groups. Get all subscriber groups configured for a specific Trust Center. Use this to manage notification groups and communication preferences.", + parameters: ListTrustCenterSubscriberGroupsInput, +}; + +export const ListTrustCenterHistoricalAccessRequestsTool: Tool< + typeof ListTrustCenterHistoricalAccessRequestsInput +> = { + name: "list_trust_center_historical_access_requests", + description: + "List Trust Center historical access requests. Get all past access requests for a specific Trust Center including approved, denied, and expired requests for audit and compliance tracking.", + parameters: ListTrustCenterHistoricalAccessRequestsInput, +}; + +export const ListTrustCenterSubscribersTool: Tool< + typeof ListTrustCenterSubscribersInput +> = { + name: "list_trust_center_subscribers", + description: + "List Trust Center subscribers. Get all subscribers to a specific Trust Center for update notifications and communication management.", + parameters: ListTrustCenterSubscribersInput, +}; + // 4. Implementation Functions export async function getTrustCenter( args: z.infer, @@ -310,3 +501,129 @@ export async function getTrustCenterDocument( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +export async function getTrustCenterResourceMedia( + args: z.infer, +): Promise { + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/resources/${String(args.resourceId)}/media`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function listTrustCenterSubprocessors( + args: z.infer, +): Promise { + const { slugId, ...params } = args; + const url = buildUrl( + `/v1/trust-centers/${String(slugId)}/subprocessors`, + params, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function getTrustCenterSubprocessor( + args: z.infer, +): Promise { + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/subprocessors/${String(args.subprocessorId)}`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function listTrustCenterUpdates( + args: z.infer, +): Promise { + const { slugId, ...params } = args; + const url = buildUrl(`/v1/trust-centers/${String(slugId)}/updates`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function getTrustCenterUpdate( + args: z.infer, +): Promise { + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/updates/${String(args.updateId)}`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function listTrustCenterViewers( + args: z.infer, +): Promise { + const { slugId, ...params } = args; + const url = buildUrl(`/v1/trust-centers/${String(slugId)}/viewers`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function getTrustCenterViewer( + args: z.infer, +): Promise { + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/viewers/${String(args.viewerId)}`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function getTrustCenterSubscriber( + args: z.infer, +): Promise { + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/subscribers/${String(args.subscriberId)}`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function getTrustCenterSubscriberGroup( + args: z.infer, +): Promise { + const url = buildUrl( + `/v1/trust-centers/${String(args.slugId)}/subscriber-groups/${String(args.subscriberGroupId)}`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function listTrustCenterSubscriberGroups( + args: z.infer, +): Promise { + const { slugId, ...params } = args; + const url = buildUrl( + `/v1/trust-centers/${String(slugId)}/subscriber-groups`, + params, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function listTrustCenterHistoricalAccessRequests( + args: z.infer, +): Promise { + const { slugId, ...params } = args; + const url = buildUrl( + `/v1/trust-centers/${String(slugId)}/access-requests/historical`, + params, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} + +export async function listTrustCenterSubscribers( + args: z.infer, +): Promise { + const { slugId, ...params } = args; + const url = buildUrl( + `/v1/trust-centers/${String(slugId)}/subscribers`, + params, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} From 7393b803874bbdcb61b06e3114b0766654d75f5f Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Wed, 24 Sep 2025 16:31:53 -0400 Subject: [PATCH 19/24] Refactor to use an automated tool registry --- .gitignore | 5 +- src/index.ts | 716 +------------------ src/operations/README.md | 140 +++- src/operations/controls.ts | 11 + src/operations/discovered-vendors.ts | 11 + src/operations/documents.ts | 12 + src/operations/frameworks.ts | 9 + src/operations/groups.ts | 9 + src/operations/integrations.ts | 18 + src/operations/monitored-computers.ts | 8 + src/operations/people.ts | 8 + src/operations/policies.ts | 8 + src/operations/risks.ts | 8 + src/operations/tests.ts | 9 + src/operations/trust-centers.ts | 127 +++- src/operations/vendor-risk-attributes.ts | 7 + src/operations/vendors.ts | 16 + src/operations/vulnerabilities.ts | 8 + src/operations/vulnerability-remediations.ts | 10 + src/operations/vulnerable-assets.ts | 8 + src/registry.ts | 78 ++ 21 files changed, 501 insertions(+), 725 deletions(-) create mode 100644 src/registry.ts diff --git a/.gitignore b/.gitignore index 83ca4f2..8d4ce3d 100644 --- a/.gitignore +++ b/.gitignore @@ -142,4 +142,7 @@ build/ CLAUDE.md # backup files -*.bak* \ No newline at end of file +*.bak* + +# Mac filesystem +*.DS_store \ No newline at end of file diff --git a/src/index.ts b/src/index.ts index d9f1cac..18e9030 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,720 +2,40 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; -import { - listTestEntities, - ListTestEntitiesTool, - listTests, - ListTestsTool, - getTest, - GetTestTool, -} from "./operations/tests.js"; -import { - ListFrameworkControlsTool, - ListFrameworksTool, - GetFrameworkTool, - listFrameworkControls, - listFrameworks, - getFramework, -} from "./operations/frameworks.js"; -import { - ListControlsTool, - ListControlTestsTool, - ListLibraryControlsTool, - ListControlDocumentsTool, - GetControlTool, - listControls, - listControlTests, - listLibraryControls, - listControlDocuments, - getControl, -} from "./operations/controls.js"; -import { - listRisks, - ListRisksTool, - getRisk, - GetRiskTool, -} from "./operations/risks.js"; -import { - listIntegrations, - ListIntegrationsTool, - getIntegration, - GetIntegrationTool, - listIntegrationResourceKinds, - ListIntegrationResourceKindsTool, - getIntegrationResourceKindDetails, - GetIntegrationResourceKindDetailsTool, - listIntegrationResources, - ListIntegrationResourcesTool, - getIntegrationResource, - GetIntegrationResourceTool, -} from "./operations/integrations.js"; -import { - listVendors, - ListVendorsTool, - getVendor, - GetVendorTool, - listVendorDocuments, - ListVendorDocumentsTool, - listVendorFindings, - ListVendorFindingsTool, - listVendorSecurityReviews, - ListVendorSecurityReviewsTool, - getVendorSecurityReview, - GetVendorSecurityReviewTool, - listVendorSecurityReviewDocuments, - ListVendorSecurityReviewDocumentsTool, -} from "./operations/vendors.js"; -import { - listDocuments, - ListDocumentsTool, - getDocument, - GetDocumentTool, - listDocumentControls, - ListDocumentControlsTool, - listDocumentLinks, - ListDocumentLinksTool, - listDocumentUploads, - ListDocumentUploadsTool, - downloadDocumentFile, - DownloadDocumentFileTool, -} from "./operations/documents.js"; -import { - listPolicies, - ListPoliciesTool, - getPolicy, - GetPolicyTool, -} from "./operations/policies.js"; -import { - listDiscoveredVendors, - ListDiscoveredVendorsTool, - listDiscoveredVendorAccounts, - ListDiscoveredVendorAccountsTool, -} from "./operations/discovered-vendors.js"; -import { - listGroups, - ListGroupsTool, - getGroup, - GetGroupTool, - listGroupPeople, - ListGroupPeopleTool, -} from "./operations/groups.js"; -import { - listPeople, - ListPeopleTool, - getPerson, - GetPersonTool, -} from "./operations/people.js"; -import { - listVulnerabilities, - ListVulnerabilitiesTool, - getVulnerability, - GetVulnerabilityTool, -} from "./operations/vulnerabilities.js"; -import { - listVulnerabilityRemediations, - ListVulnerabilityRemediationsTool, -} from "./operations/vulnerability-remediations.js"; -import { - listVulnerableAssets, - ListVulnerableAssetsTool, - getVulnerableAsset, - GetVulnerableAssetTool, -} from "./operations/vulnerable-assets.js"; -import { - listMonitoredComputers, - ListMonitoredComputersTool, - getMonitoredComputer, - GetMonitoredComputerTool, -} from "./operations/monitored-computers.js"; -import { - listVendorRiskAttributes, - ListVendorRiskAttributesTool, -} from "./operations/vendor-risk-attributes.js"; -import { - getTrustCenter, - GetTrustCenterTool, - listTrustCenterAccessRequests, - ListTrustCenterAccessRequestsTool, - getTrustCenterAccessRequest, - GetTrustCenterAccessRequestTool, - listTrustCenterViewerActivityEvents, - ListTrustCenterViewerActivityEventsTool, - listTrustCenterControlCategories, - ListTrustCenterControlCategoriesTool, - getTrustCenterControlCategory, - GetTrustCenterControlCategoryTool, - listTrustCenterControls, - ListTrustCenterControlsTool, - getTrustCenterControl, - GetTrustCenterControlTool, - listTrustCenterFaqs, - ListTrustCenterFaqsTool, - getTrustCenterFaq, - GetTrustCenterFaqTool, - listTrustCenterResources, - ListTrustCenterResourcesTool, - getTrustCenterDocument, - GetTrustCenterDocumentTool, - getTrustCenterResourceMedia, - GetTrustCenterResourceMediaTool, - listTrustCenterSubprocessors, - ListTrustCenterSubprocessorsTool, - getTrustCenterSubprocessor, - GetTrustCenterSubprocessorTool, - listTrustCenterUpdates, - ListTrustCenterUpdatesTool, - getTrustCenterUpdate, - GetTrustCenterUpdateTool, - listTrustCenterViewers, - ListTrustCenterViewersTool, - getTrustCenterViewer, - GetTrustCenterViewerTool, - getTrustCenterSubscriber, - GetTrustCenterSubscriberTool, - getTrustCenterSubscriberGroup, - GetTrustCenterSubscriberGroupTool, - listTrustCenterSubscriberGroups, - ListTrustCenterSubscriberGroupsTool, - listTrustCenterHistoricalAccessRequests, - ListTrustCenterHistoricalAccessRequestsTool, - listTrustCenterSubscribers, - ListTrustCenterSubscribersTool, -} from "./operations/trust-centers.js"; +import { registerAllOperations } from "./registry.js"; import { initializeToken } from "./auth.js"; const server = new McpServer({ name: "vanta-mcp", version: "1.0.0", - description: - "Model Context Protocol server for Vanta's automated security compliance platform. Provides access to security tests, compliance frameworks, and security controls for SOC 2, ISO 27001, HIPAA, GDPR and other standards.", }); -server.tool( - ListTestsTool.name, - ListTestsTool.description, - ListTestsTool.parameters.shape, - listTests, -); - -server.tool( - GetTestTool.name, - GetTestTool.description, - GetTestTool.parameters.shape, - getTest, -); - -server.tool( - ListTestEntitiesTool.name, - ListTestEntitiesTool.description, - ListTestEntitiesTool.parameters.shape, - listTestEntities, -); - -server.tool( - ListFrameworksTool.name, - ListFrameworksTool.description, - ListFrameworksTool.parameters.shape, - listFrameworks, -); - -server.tool( - ListFrameworkControlsTool.name, - ListFrameworkControlsTool.description, - ListFrameworkControlsTool.parameters.shape, - listFrameworkControls, -); - -server.tool( - GetFrameworkTool.name, - GetFrameworkTool.description, - GetFrameworkTool.parameters.shape, - getFramework, -); - -server.tool( - ListControlsTool.name, - ListControlsTool.description, - ListControlsTool.parameters.shape, - listControls, -); - -server.tool( - ListControlTestsTool.name, - ListControlTestsTool.description, - ListControlTestsTool.parameters.shape, - listControlTests, -); - -server.tool( - ListLibraryControlsTool.name, - ListLibraryControlsTool.description, - ListLibraryControlsTool.parameters.shape, - listLibraryControls, -); - -server.tool( - ListControlDocumentsTool.name, - ListControlDocumentsTool.description, - ListControlDocumentsTool.parameters.shape, - listControlDocuments, -); - -server.tool( - GetControlTool.name, - GetControlTool.description, - GetControlTool.parameters.shape, - getControl, -); - -server.tool( - ListRisksTool.name, - ListRisksTool.description, - ListRisksTool.parameters.shape, - listRisks, -); - -server.tool( - GetRiskTool.name, - GetRiskTool.description, - GetRiskTool.parameters.shape, - getRisk, -); - -server.tool( - ListIntegrationsTool.name, - ListIntegrationsTool.description, - ListIntegrationsTool.parameters.shape, - listIntegrations, -); - -server.tool( - GetIntegrationTool.name, - GetIntegrationTool.description, - GetIntegrationTool.parameters.shape, - getIntegration, -); - -server.tool( - ListIntegrationResourceKindsTool.name, - ListIntegrationResourceKindsTool.description, - ListIntegrationResourceKindsTool.parameters.shape, - listIntegrationResourceKinds, -); - -server.tool( - GetIntegrationResourceKindDetailsTool.name, - GetIntegrationResourceKindDetailsTool.description, - GetIntegrationResourceKindDetailsTool.parameters.shape, - getIntegrationResourceKindDetails, -); - -server.tool( - ListIntegrationResourcesTool.name, - ListIntegrationResourcesTool.description, - ListIntegrationResourcesTool.parameters.shape, - listIntegrationResources, -); - -server.tool( - GetIntegrationResourceTool.name, - GetIntegrationResourceTool.description, - GetIntegrationResourceTool.parameters.shape, - getIntegrationResource, -); - -server.tool( - ListVendorsTool.name, - ListVendorsTool.description, - ListVendorsTool.parameters.shape, - listVendors, -); - -server.tool( - GetVendorTool.name, - GetVendorTool.description, - GetVendorTool.parameters.shape, - getVendor, -); - -server.tool( - ListVendorDocumentsTool.name, - ListVendorDocumentsTool.description, - ListVendorDocumentsTool.parameters.shape, - listVendorDocuments, -); - -server.tool( - ListVendorFindingsTool.name, - ListVendorFindingsTool.description, - ListVendorFindingsTool.parameters.shape, - listVendorFindings, -); - -server.tool( - ListVendorSecurityReviewsTool.name, - ListVendorSecurityReviewsTool.description, - ListVendorSecurityReviewsTool.parameters.shape, - listVendorSecurityReviews, -); - -server.tool( - GetVendorSecurityReviewTool.name, - GetVendorSecurityReviewTool.description, - GetVendorSecurityReviewTool.parameters.shape, - getVendorSecurityReview, -); - -server.tool( - ListVendorSecurityReviewDocumentsTool.name, - ListVendorSecurityReviewDocumentsTool.description, - ListVendorSecurityReviewDocumentsTool.parameters.shape, - listVendorSecurityReviewDocuments, -); - -server.tool( - ListDocumentsTool.name, - ListDocumentsTool.description, - ListDocumentsTool.parameters.shape, - listDocuments, -); - -server.tool( - GetDocumentTool.name, - GetDocumentTool.description, - GetDocumentTool.parameters.shape, - getDocument, -); - -server.tool( - ListDocumentControlsTool.name, - ListDocumentControlsTool.description, - ListDocumentControlsTool.parameters.shape, - listDocumentControls, -); - -server.tool( - ListDocumentLinksTool.name, - ListDocumentLinksTool.description, - ListDocumentLinksTool.parameters.shape, - listDocumentLinks, -); - -server.tool( - ListDocumentUploadsTool.name, - ListDocumentUploadsTool.description, - ListDocumentUploadsTool.parameters.shape, - listDocumentUploads, -); - -server.tool( - DownloadDocumentFileTool.name, - DownloadDocumentFileTool.description, - DownloadDocumentFileTool.parameters.shape, - downloadDocumentFile, -); - -server.tool( - ListPoliciesTool.name, - ListPoliciesTool.description, - ListPoliciesTool.parameters.shape, - listPolicies, -); - -server.tool( - GetPolicyTool.name, - GetPolicyTool.description, - GetPolicyTool.parameters.shape, - getPolicy, -); - -server.tool( - ListDiscoveredVendorsTool.name, - ListDiscoveredVendorsTool.description, - ListDiscoveredVendorsTool.parameters.shape, - listDiscoveredVendors, -); - -server.tool( - ListDiscoveredVendorAccountsTool.name, - ListDiscoveredVendorAccountsTool.description, - ListDiscoveredVendorAccountsTool.parameters.shape, - listDiscoveredVendorAccounts, -); - -server.tool( - ListGroupsTool.name, - ListGroupsTool.description, - ListGroupsTool.parameters.shape, - listGroups, -); - -server.tool( - GetGroupTool.name, - GetGroupTool.description, - GetGroupTool.parameters.shape, - getGroup, -); - -server.tool( - ListGroupPeopleTool.name, - ListGroupPeopleTool.description, - ListGroupPeopleTool.parameters.shape, - listGroupPeople, -); - -server.tool( - ListPeopleTool.name, - ListPeopleTool.description, - ListPeopleTool.parameters.shape, - listPeople, -); - -server.tool( - GetPersonTool.name, - GetPersonTool.description, - GetPersonTool.parameters.shape, - getPerson, -); - -server.tool( - ListVulnerabilitiesTool.name, - ListVulnerabilitiesTool.description, - ListVulnerabilitiesTool.parameters.shape, - listVulnerabilities, -); - -server.tool( - GetVulnerabilityTool.name, - GetVulnerabilityTool.description, - GetVulnerabilityTool.parameters.shape, - getVulnerability, -); - -server.tool( - ListVulnerabilityRemediationsTool.name, - ListVulnerabilityRemediationsTool.description, - ListVulnerabilityRemediationsTool.parameters.shape, - listVulnerabilityRemediations, -); - -server.tool( - ListVulnerableAssetsTool.name, - ListVulnerableAssetsTool.description, - ListVulnerableAssetsTool.parameters.shape, - listVulnerableAssets, -); - -server.tool( - GetVulnerableAssetTool.name, - GetVulnerableAssetTool.description, - GetVulnerableAssetTool.parameters.shape, - getVulnerableAsset, -); - -server.tool( - ListMonitoredComputersTool.name, - ListMonitoredComputersTool.description, - ListMonitoredComputersTool.parameters.shape, - listMonitoredComputers, -); - -server.tool( - GetMonitoredComputerTool.name, - GetMonitoredComputerTool.description, - GetMonitoredComputerTool.parameters.shape, - getMonitoredComputer, -); - -server.tool( - ListVendorRiskAttributesTool.name, - ListVendorRiskAttributesTool.description, - ListVendorRiskAttributesTool.parameters.shape, - listVendorRiskAttributes, -); - -server.tool( - GetTrustCenterTool.name, - GetTrustCenterTool.description, - GetTrustCenterTool.parameters.shape, - getTrustCenter, -); - -server.tool( - ListTrustCenterAccessRequestsTool.name, - ListTrustCenterAccessRequestsTool.description, - ListTrustCenterAccessRequestsTool.parameters.shape, - listTrustCenterAccessRequests, -); - -server.tool( - GetTrustCenterAccessRequestTool.name, - GetTrustCenterAccessRequestTool.description, - GetTrustCenterAccessRequestTool.parameters.shape, - getTrustCenterAccessRequest, -); - -server.tool( - ListTrustCenterViewerActivityEventsTool.name, - ListTrustCenterViewerActivityEventsTool.description, - ListTrustCenterViewerActivityEventsTool.parameters.shape, - listTrustCenterViewerActivityEvents, -); - -server.tool( - ListTrustCenterControlCategoriesTool.name, - ListTrustCenterControlCategoriesTool.description, - ListTrustCenterControlCategoriesTool.parameters.shape, - listTrustCenterControlCategories, -); - -server.tool( - GetTrustCenterControlCategoryTool.name, - GetTrustCenterControlCategoryTool.description, - GetTrustCenterControlCategoryTool.parameters.shape, - getTrustCenterControlCategory, -); - -server.tool( - ListTrustCenterControlsTool.name, - ListTrustCenterControlsTool.description, - ListTrustCenterControlsTool.parameters.shape, - listTrustCenterControls, -); - -server.tool( - GetTrustCenterControlTool.name, - GetTrustCenterControlTool.description, - GetTrustCenterControlTool.parameters.shape, - getTrustCenterControl, -); - -server.tool( - ListTrustCenterFaqsTool.name, - ListTrustCenterFaqsTool.description, - ListTrustCenterFaqsTool.parameters.shape, - listTrustCenterFaqs, -); - -server.tool( - GetTrustCenterFaqTool.name, - GetTrustCenterFaqTool.description, - GetTrustCenterFaqTool.parameters.shape, - getTrustCenterFaq, -); - -server.tool( - ListTrustCenterResourcesTool.name, - ListTrustCenterResourcesTool.description, - ListTrustCenterResourcesTool.parameters.shape, - listTrustCenterResources, -); - -server.tool( - GetTrustCenterDocumentTool.name, - GetTrustCenterDocumentTool.description, - GetTrustCenterDocumentTool.parameters.shape, - getTrustCenterDocument, -); - -server.tool( - GetTrustCenterResourceMediaTool.name, - GetTrustCenterResourceMediaTool.description, - GetTrustCenterResourceMediaTool.parameters.shape, - getTrustCenterResourceMedia, -); - -server.tool( - ListTrustCenterSubprocessorsTool.name, - ListTrustCenterSubprocessorsTool.description, - ListTrustCenterSubprocessorsTool.parameters.shape, - listTrustCenterSubprocessors, -); - -server.tool( - GetTrustCenterSubprocessorTool.name, - GetTrustCenterSubprocessorTool.description, - GetTrustCenterSubprocessorTool.parameters.shape, - getTrustCenterSubprocessor, -); - -server.tool( - ListTrustCenterUpdatesTool.name, - ListTrustCenterUpdatesTool.description, - ListTrustCenterUpdatesTool.parameters.shape, - listTrustCenterUpdates, -); - -server.tool( - GetTrustCenterUpdateTool.name, - GetTrustCenterUpdateTool.description, - GetTrustCenterUpdateTool.parameters.shape, - getTrustCenterUpdate, -); - -server.tool( - ListTrustCenterViewersTool.name, - ListTrustCenterViewersTool.description, - ListTrustCenterViewersTool.parameters.shape, - listTrustCenterViewers, -); - -server.tool( - GetTrustCenterViewerTool.name, - GetTrustCenterViewerTool.description, - GetTrustCenterViewerTool.parameters.shape, - getTrustCenterViewer, -); - -server.tool( - GetTrustCenterSubscriberTool.name, - GetTrustCenterSubscriberTool.description, - GetTrustCenterSubscriberTool.parameters.shape, - getTrustCenterSubscriber, -); - -server.tool( - GetTrustCenterSubscriberGroupTool.name, - GetTrustCenterSubscriberGroupTool.description, - GetTrustCenterSubscriberGroupTool.parameters.shape, - getTrustCenterSubscriberGroup, -); - -server.tool( - ListTrustCenterSubscriberGroupsTool.name, - ListTrustCenterSubscriberGroupsTool.description, - ListTrustCenterSubscriberGroupsTool.parameters.shape, - listTrustCenterSubscriberGroups, -); - -server.tool( - ListTrustCenterHistoricalAccessRequestsTool.name, - ListTrustCenterHistoricalAccessRequestsTool.description, - ListTrustCenterHistoricalAccessRequestsTool.parameters.shape, - listTrustCenterHistoricalAccessRequests, -); - -server.tool( - ListTrustCenterSubscribersTool.name, - ListTrustCenterSubscribersTool.description, - ListTrustCenterSubscribersTool.parameters.shape, - listTrustCenterSubscribers, -); - async function main() { try { await initializeToken(); console.error("Token initialized successfully"); + + // Register all tools automatically + await registerAllOperations(server); + + // Connect to stdio transport + const transport = new StdioServerTransport(); + await server.connect(transport); + + console.error("🚀 Vanta MCP Server started successfully!"); } catch (error) { - console.error("Failed to initialize token:", error); + console.error("Failed to start Vanta MCP Server:", error); process.exit(1); } - - const transport = new StdioServerTransport(); - await server.connect(transport); } +// Handle shutdown gracefully +process.on("SIGINT", () => { + console.error("Shutting down Vanta MCP Server..."); + process.exit(0); +}); + main().catch(error => { - console.error("Fatal error in main():", error); + console.error("Fatal error:", error); process.exit(1); }); diff --git a/src/operations/README.md b/src/operations/README.md index 5b392b8..6264b92 100644 --- a/src/operations/README.md +++ b/src/operations/README.md @@ -10,6 +10,7 @@ This document explains the architecture, patterns, and conventions used in the V - [DRY Utilities](#dry-utilities) - [Schema Factory Functions](#schema-factory-functions) - [Request Handler Utilities](#request-handler-utilities) +- [Automated Tool Registry System](#automated-tool-registry-system) - [Creating New Operations](#creating-new-operations) - [Best Practices](#best-practices) - [Examples](#examples) @@ -25,6 +26,7 @@ The operations layer provides a clean, consistent interface to the Vanta API. Ea 3. **Type Safety**: Full TypeScript support with proper type definitions 4. **Consistent Error Handling**: Standardized error responses across all operations 5. **Schema Factories**: Reusable Zod schema generators for common patterns +6. **Automated Registry**: Zero-maintenance tool registration system ## File Structure @@ -68,6 +70,14 @@ export async function listResources( ): Promise { return makePaginatedGetRequest("/v1/resources", args); } + +// 5. Registry Export (REQUIRED for auto-registration) +export default { + tools: [ + { tool: ListResourcesTool, handler: listResources }, + { tool: GetResourceTool, handler: getResource }, + ], +}; ``` ## Naming Conventions @@ -259,36 +269,35 @@ export async function listNewResources( export async function getNewResource( args: z.infer, ): Promise { - return makeGetByIdRequest("new-resources", args.newResourceId); + return makeGetByIdRequest("/v1/new-resources", args.newResourceId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListNewResourcesTool, handler: listNewResources }, + { tool: GetNewResourceTool, handler: getNewResource }, + ], +}; ``` -### Step 2: Register in index.ts +### Step 2: Verify Registry Export + +Ensure your operations file includes the required registry export: ```typescript -// Add imports -import { - ListNewResourcesTool, - GetNewResourceTool, - listNewResources, - getNewResource, -} from "./operations/new-resource.js"; - -// Register tools -server.tool( - ListNewResourcesTool.name, - ListNewResourcesTool.description, - ListNewResourcesTool.parameters.shape, - listNewResources, -); -server.tool( - GetNewResourceTool.name, - GetNewResourceTool.description, - GetNewResourceTool.parameters.shape, - getNewResource, -); +// At the end of your operations file +export default { + tools: [ + { tool: ListNewResourcesTool, handler: listNewResources }, + { tool: GetNewResourceTool, handler: getNewResource }, + // Add all tools from this file here + ], +}; ``` +**That's it!** Your tools will be automatically registered when the server starts. No changes to `index.ts` are needed. + ### Step 3: Add to eval.ts ```typescript @@ -486,6 +495,89 @@ export async function listVendorDocuments( - Add evaluation test cases for all new tools in `eval.ts` - Update `eval/README.md` with new test descriptions +## Automated Tool Registry System + +### Overview + +The Vanta MCP Server uses an automated tool registry system that eliminates the need for manual tool registration in `index.ts`. + +### Key Benefits + +- **✅ Zero Maintenance**: Adding new tools requires no changes to `index.ts` +- **✅ Auto-Discovery**: New operations files are automatically detected and loaded +- **✅ Type Safety**: Full TypeScript support throughout the registration process +- **✅ Error Prevention**: No risk of forgetting to register new tools +- **✅ Scalability**: System grows effortlessly as you add more operations + +### How It Works + +1. **Registry Export**: Each operations file exports a `default` object with all its tools +2. **Auto-Discovery**: `src/registry.ts` imports all operations modules dynamically +3. **Automatic Registration**: `registerAllOperations()` registers each tool with the MCP server +4. **Single Call**: `index.ts` simply calls `await registerAllOperations(server)` + +### Required Registry Export + +Every operations file MUST include this export at the end: + +```typescript +// Registry export for automated tool registration +export default { + tools: [ + { tool: ToolDefinition, handler: HandlerFunction }, + { tool: AnotherTool, handler: anotherHandler }, + // ... all tools in this file + ], +}; +``` + +**⚠️ Without this export, your tools will NOT be registered automatically!** + +### Adding New Tools + +To add a new tool to an existing operations file: + +1. Create your tool definition and handler function (following our patterns) +2. Add the tool entry to the `tools` array in the default export +3. The tool will be automatically registered on the next server restart + +Example: + +```typescript +export default { + tools: [ + { tool: ExistingTool, handler: existingHandler }, + { tool: NewTool, handler: newHandler }, // ← Just add here! + ], +}; +``` + +### Registry Implementation + +The automated registry system works through a simple pattern: + +**Operations File Pattern:** + +```typescript +// At the end of each operations file +export default { + tools: [ + { tool: ToolDefinition, handler: HandlerFunction }, + // ... all tools in this file + ], +}; +``` + +**Main Server Registration:** + +```typescript +// index.ts +import { registerAllOperations } from "./registry.js"; + +await registerAllOperations(server); +// ✅ Automatically registers all tools from all operations files +``` + --- -This architecture provides a maintainable, consistent foundation for extending the Vanta MCP Server with new operations while ensuring code quality and developer productivity. +This architecture provides a maintainable, consistent, and **highly scalable** foundation for extending the Vanta MCP Server with new operations while ensuring code quality and developer productivity. The automated registry system ensures that adding new functionality is effortless and error-free! diff --git a/src/operations/controls.ts b/src/operations/controls.ts index ecbe481..dd9dbe6 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -114,3 +114,14 @@ export async function getControl( ): Promise { return makeGetByIdRequest("/v1/controls", args.controlId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListControlsTool, handler: listControls }, + { tool: ListControlTestsTool, handler: listControlTests }, + { tool: ListLibraryControlsTool, handler: listLibraryControls }, + { tool: ListControlDocumentsTool, handler: listControlDocuments }, + { tool: GetControlTool, handler: getControl }, + ], +}; diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts index ca547b6..4aad23d 100644 --- a/src/operations/discovered-vendors.ts +++ b/src/operations/discovered-vendors.ts @@ -57,3 +57,14 @@ export async function listDiscoveredVendorAccounts( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListDiscoveredVendorsTool, handler: listDiscoveredVendors }, + { + tool: ListDiscoveredVendorAccountsTool, + handler: listDiscoveredVendorAccounts, + }, + ], +}; diff --git a/src/operations/documents.ts b/src/operations/documents.ts index 5ddb144..1a27930 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -195,3 +195,15 @@ Note: This is a binary file (${contentType.split("/")[0]} format) that cannot be ], }; } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListDocumentsTool, handler: listDocuments }, + { tool: GetDocumentTool, handler: getDocument }, + { tool: ListDocumentControlsTool, handler: listDocumentControls }, + { tool: ListDocumentLinksTool, handler: listDocumentLinks }, + { tool: ListDocumentUploadsTool, handler: listDocumentUploads }, + { tool: DownloadDocumentFileTool, handler: downloadDocumentFile }, + ], +}; diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index b49b6a5..d096a9b 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -75,3 +75,12 @@ export async function getFramework( ): Promise { return makeGetByIdRequest("/v1/frameworks", args.frameworkId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListFrameworksTool, handler: listFrameworks }, + { tool: ListFrameworkControlsTool, handler: listFrameworkControls }, + { tool: GetFrameworkTool, handler: getFramework }, + ], +}; diff --git a/src/operations/groups.ts b/src/operations/groups.ts index 5abf0b3..691b2c2 100644 --- a/src/operations/groups.ts +++ b/src/operations/groups.ts @@ -71,3 +71,12 @@ export async function listGroupPeople( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListGroupsTool, handler: listGroups }, + { tool: GetGroupTool, handler: getGroup }, + { tool: ListGroupPeopleTool, handler: listGroupPeople }, + ], +}; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index cca7471..59c7c9b 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -166,3 +166,21 @@ export async function getIntegrationResource( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListIntegrationsTool, handler: listIntegrations }, + { tool: GetIntegrationTool, handler: getIntegration }, + { + tool: ListIntegrationResourceKindsTool, + handler: listIntegrationResourceKinds, + }, + { + tool: GetIntegrationResourceKindDetailsTool, + handler: getIntegrationResourceKindDetails, + }, + { tool: ListIntegrationResourcesTool, handler: listIntegrationResources }, + { tool: GetIntegrationResourceTool, handler: getIntegrationResource }, + ], +}; diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts index aa2d1de..1767087 100644 --- a/src/operations/monitored-computers.ts +++ b/src/operations/monitored-computers.ts @@ -48,3 +48,11 @@ export async function getMonitoredComputer( ): Promise { return makeGetByIdRequest("/v1/monitored-computers", args.computerId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListMonitoredComputersTool, handler: listMonitoredComputers }, + { tool: GetMonitoredComputerTool, handler: getMonitoredComputer }, + ], +}; diff --git a/src/operations/people.ts b/src/operations/people.ts index f9fc5f2..6990e0c 100644 --- a/src/operations/people.ts +++ b/src/operations/people.ts @@ -45,3 +45,11 @@ export async function getPerson( ): Promise { return makeGetByIdRequest("/v1/people", args.personId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListPeopleTool, handler: listPeople }, + { tool: GetPersonTool, handler: getPerson }, + ], +}; diff --git a/src/operations/policies.ts b/src/operations/policies.ts index 561180c..2ca181e 100644 --- a/src/operations/policies.ts +++ b/src/operations/policies.ts @@ -45,3 +45,11 @@ export async function getPolicy( ): Promise { return makeGetByIdRequest("/v1/policies", args.policyId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListPoliciesTool, handler: listPolicies }, + { tool: GetPolicyTool, handler: getPolicy }, + ], +}; diff --git a/src/operations/risks.ts b/src/operations/risks.ts index fd56f28..723caf7 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -51,3 +51,11 @@ export async function getRisk( ): Promise { return makeGetByIdRequest("/v1/risk-scenarios", args.riskId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListRisksTool, handler: listRisks }, + { tool: GetRiskTool, handler: getRisk }, + ], +}; diff --git a/src/operations/tests.ts b/src/operations/tests.ts index af245b4..91f191b 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -71,3 +71,12 @@ export async function getTest( ): Promise { return makeGetByIdRequest("/v1/tests", args.testId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListTestsTool, handler: listTests }, + { tool: ListTestEntitiesTool, handler: listTestEntities }, + { tool: GetTestTool, handler: getTest }, + ], +}; diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts index 1e6d169..bea0c11 100644 --- a/src/operations/trust-centers.ts +++ b/src/operations/trust-centers.ts @@ -284,7 +284,7 @@ export const GetTrustCenterResourceMediaTool: Tool< > = { name: "get_trust_center_resource_media", description: - "Download Trust Center document media. Get the actual uploaded document/media file for a Trust Center resource. Use this to download compliance documents, certifications, and other materials for review or audit purposes.", + "Download Trust Center document media. Get the actual uploaded document/media file for a Trust Center resource. Intelligently handles different MIME types: returns text content for readable files (text/*, JSON, XML, CSV, JavaScript) and metadata information for binary files (images, videos, PDFs, etc.). Use this to download compliance documents, certifications, and other materials for review or audit purposes.", parameters: GetTrustCenterResourceMediaInput, }; @@ -509,7 +509,64 @@ export async function getTrustCenterResourceMedia( `/v1/trust-centers/${String(args.slugId)}/resources/${String(args.resourceId)}/media`, ); const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); + + if (!response.ok) { + return handleApiResponse(response); + } + + // Get the content type from the response headers + const contentType = + response.headers.get("content-type") ?? "application/octet-stream"; + const contentLength = response.headers.get("content-length"); + + // Handle text-based MIME types - return content that LLMs can process + if ( + contentType.startsWith("text/") || + contentType.includes("application/json") || + contentType.includes("application/xml") || + contentType.includes("application/javascript") || + contentType.includes("application/csv") || + contentType.includes("text/csv") + ) { + try { + const textContent = await response.text(); + return { + content: [ + { + type: "text" as const, + text: `Trust Center Resource Media Content (${contentType}):\n\n${textContent}`, + }, + ], + }; + } catch (error) { + return { + content: [ + { + type: "text" as const, + text: `Error reading text content: ${error instanceof Error ? error.message : "Unknown error"}`, + }, + ], + isError: true, + }; + } + } + + // For binary files, return metadata about the file + return { + content: [ + { + type: "text" as const, + text: `Trust Center Resource Media File Information: +- Content Type: ${contentType} +- Content Length: ${contentLength ? `${contentLength} bytes` : "Unknown"} +- File Type: ${contentType.startsWith("image/") ? "Image" : contentType.startsWith("video/") ? "Video" : contentType.startsWith("audio/") ? "Audio" : contentType.startsWith("application/pdf") ? "PDF Document" : "Binary File"} +- Resource ID: ${String(args.resourceId)} +- Trust Center: ${String(args.slugId)} + +Note: This is a binary file. Use appropriate tools to download and process the actual file content.`, + }, + ], + }; } export async function listTrustCenterSubprocessors( @@ -627,3 +684,69 @@ export async function listTrustCenterSubscribers( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: GetTrustCenterTool, handler: getTrustCenter }, + { + tool: ListTrustCenterAccessRequestsTool, + handler: listTrustCenterAccessRequests, + }, + { + tool: GetTrustCenterAccessRequestTool, + handler: getTrustCenterAccessRequest, + }, + { + tool: ListTrustCenterViewerActivityEventsTool, + handler: listTrustCenterViewerActivityEvents, + }, + { + tool: ListTrustCenterControlCategoriesTool, + handler: listTrustCenterControlCategories, + }, + { + tool: GetTrustCenterControlCategoryTool, + handler: getTrustCenterControlCategory, + }, + { tool: ListTrustCenterControlsTool, handler: listTrustCenterControls }, + { tool: GetTrustCenterControlTool, handler: getTrustCenterControl }, + { tool: ListTrustCenterFaqsTool, handler: listTrustCenterFaqs }, + { tool: GetTrustCenterFaqTool, handler: getTrustCenterFaq }, + { tool: ListTrustCenterResourcesTool, handler: listTrustCenterResources }, + { tool: GetTrustCenterDocumentTool, handler: getTrustCenterDocument }, + { + tool: GetTrustCenterResourceMediaTool, + handler: getTrustCenterResourceMedia, + }, + { + tool: ListTrustCenterSubprocessorsTool, + handler: listTrustCenterSubprocessors, + }, + { + tool: GetTrustCenterSubprocessorTool, + handler: getTrustCenterSubprocessor, + }, + { tool: ListTrustCenterUpdatesTool, handler: listTrustCenterUpdates }, + { tool: GetTrustCenterUpdateTool, handler: getTrustCenterUpdate }, + { tool: ListTrustCenterViewersTool, handler: listTrustCenterViewers }, + { tool: GetTrustCenterViewerTool, handler: getTrustCenterViewer }, + { tool: GetTrustCenterSubscriberTool, handler: getTrustCenterSubscriber }, + { + tool: GetTrustCenterSubscriberGroupTool, + handler: getTrustCenterSubscriberGroup, + }, + { + tool: ListTrustCenterSubscriberGroupsTool, + handler: listTrustCenterSubscriberGroups, + }, + { + tool: ListTrustCenterHistoricalAccessRequestsTool, + handler: listTrustCenterHistoricalAccessRequests, + }, + { + tool: ListTrustCenterSubscribersTool, + handler: listTrustCenterSubscribers, + }, + ], +}; diff --git a/src/operations/vendor-risk-attributes.ts b/src/operations/vendor-risk-attributes.ts index 02e1be8..ee3b454 100644 --- a/src/operations/vendor-risk-attributes.ts +++ b/src/operations/vendor-risk-attributes.ts @@ -23,3 +23,10 @@ export async function listVendorRiskAttributes( ): Promise { return makePaginatedGetRequest("/v1/vendor-risk-attributes", args); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListVendorRiskAttributesTool, handler: listVendorRiskAttributes }, + ], +}; diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index febd632..b4fb2d9 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -176,3 +176,19 @@ export async function listVendorSecurityReviewDocuments( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListVendorsTool, handler: listVendors }, + { tool: GetVendorTool, handler: getVendor }, + { tool: ListVendorDocumentsTool, handler: listVendorDocuments }, + { tool: ListVendorFindingsTool, handler: listVendorFindings }, + { tool: ListVendorSecurityReviewsTool, handler: listVendorSecurityReviews }, + { tool: GetVendorSecurityReviewTool, handler: getVendorSecurityReview }, + { + tool: ListVendorSecurityReviewDocumentsTool, + handler: listVendorSecurityReviewDocuments, + }, + ], +}; diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index d2c46ea..a7db103 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -45,3 +45,11 @@ export async function getVulnerability( ): Promise { return makeGetByIdRequest("/v1/vulnerabilities", args.vulnerabilityId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListVulnerabilitiesTool, handler: listVulnerabilities }, + { tool: GetVulnerabilityTool, handler: getVulnerability }, + ], +}; diff --git a/src/operations/vulnerability-remediations.ts b/src/operations/vulnerability-remediations.ts index 6cafc1d..6933e04 100644 --- a/src/operations/vulnerability-remediations.ts +++ b/src/operations/vulnerability-remediations.ts @@ -23,3 +23,13 @@ export async function listVulnerabilityRemediations( ): Promise { return makePaginatedGetRequest("/v1/vulnerability-remediations", args); } + +// Registry export for automated tool registration +export default { + tools: [ + { + tool: ListVulnerabilityRemediationsTool, + handler: listVulnerabilityRemediations, + }, + ], +}; diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts index bccc7af..dd3c202 100644 --- a/src/operations/vulnerable-assets.ts +++ b/src/operations/vulnerable-assets.ts @@ -46,3 +46,11 @@ export async function getVulnerableAsset( ): Promise { return makeGetByIdRequest("/v1/vulnerable-assets", args.vulnerableAssetId); } + +// Registry export for automated tool registration +export default { + tools: [ + { tool: ListVulnerableAssetsTool, handler: listVulnerableAssets }, + { tool: GetVulnerableAssetTool, handler: getVulnerableAsset }, + ], +}; diff --git a/src/registry.ts b/src/registry.ts new file mode 100644 index 0000000..699eca0 --- /dev/null +++ b/src/registry.ts @@ -0,0 +1,78 @@ +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; + +// Tool definition interface (matches our Tool pattern) +export interface ToolDefinition { + name: string; + description: string; + parameters: z.ZodTypeAny; +} + +// Tool registry interface for operations modules +export interface ToolEntry { + tool: ToolDefinition; + handler: (args: z.infer) => Promise; +} + +export interface OperationModule { + tools: ToolEntry[]; +} + +// Helper function to register a single tool +export function registerTool( + server: McpServer, + tool: ToolDefinition, + handler: (args: z.infer) => Promise, +): void { + const parameters = tool.parameters as z.ZodObject; + server.tool(tool.name, tool.description, parameters.shape, handler); +} + +// Helper function to register all tools from a module +export function registerOperationModule( + server: McpServer, + operationModule: OperationModule, +): void { + operationModule.tools.forEach(({ tool, handler }) => { + registerTool(server, tool, handler); + }); +} + +// Auto-discovery and registration of all operations +export async function registerAllOperations(server: McpServer): Promise { + // Import all operation modules + const operations = [ + import("./operations/tests.js"), + import("./operations/frameworks.js"), + import("./operations/controls.js"), + import("./operations/risks.js"), + import("./operations/integrations.js"), + import("./operations/vendors.js"), + import("./operations/documents.js"), + import("./operations/policies.js"), + import("./operations/discovered-vendors.js"), + import("./operations/groups.js"), + import("./operations/people.js"), + import("./operations/vulnerabilities.js"), + import("./operations/vulnerability-remediations.js"), + import("./operations/vulnerable-assets.js"), + import("./operations/monitored-computers.js"), + import("./operations/vendor-risk-attributes.js"), + import("./operations/trust-centers.js"), + ]; + + // Load all modules and register their tools + const modules = await Promise.all(operations); + + let totalTools = 0; + modules.forEach(module => { + const operationModule = module.default; + registerOperationModule(server, operationModule); + totalTools += operationModule.tools.length; + }); + + console.error( + `✅ Registered ${String(totalTools)} tools from ${String(modules.length)} operation modules successfully`, + ); +} From 72a6ffc7fd9e99cc35cbe649c9de7e6a5103a039 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Wed, 24 Sep 2025 17:01:07 -0400 Subject: [PATCH 20/24] Refactor to a barrel import structure for consistency --- README.md | 51 ++++++ src/eval/eval.ts | 56 +++---- src/operations/README.md | 146 ++++++++++++++++-- .../descriptions.ts} | 16 +- src/operations/common/imports.ts | 14 ++ src/operations/{ => common}/utils.ts | 6 +- src/operations/controls.ts | 10 +- src/operations/discovered-vendors.ts | 8 +- src/operations/documents.ts | 10 +- src/operations/frameworks.ts | 10 +- src/operations/groups.ts | 8 +- src/operations/index.ts | 27 ++++ src/operations/integrations.ts | 10 +- src/operations/monitored-computers.ts | 8 +- src/operations/people.ts | 8 +- src/operations/policies.ts | 8 +- src/operations/risks.ts | 8 +- src/operations/tests.ts | 8 +- src/operations/trust-centers.ts | 10 +- src/operations/vendor-risk-attributes.ts | 11 +- src/operations/vendors.ts | 10 +- src/operations/vulnerabilities.ts | 8 +- src/operations/vulnerability-remediations.ts | 11 +- src/operations/vulnerable-assets.ts | 8 +- 24 files changed, 348 insertions(+), 122 deletions(-) rename src/operations/{global-descriptions.ts => common/descriptions.ts} (83%) create mode 100644 src/operations/common/imports.ts rename src/operations/{ => common}/utils.ts (97%) create mode 100644 src/operations/index.ts diff --git a/README.md b/README.md index f30a840..f89a28c 100644 --- a/README.md +++ b/README.md @@ -439,6 +439,57 @@ Now you can configure Claude Desktop or Cursor to use the built executable: } ``` +## Development + +This server is built with TypeScript and includes the following development tools: + +- **TypeScript**: For type safety and better development experience +- **ESLint**: For code quality and consistency +- **Automated Tool Registry**: Zero-maintenance tool registration system +- **DRY Utilities**: Centralized utilities to reduce code duplication + +### Project Structure + +``` +vanta-mcp-server/ +├── src/ +│ ├── operations/ # MCP tool implementations +│ │ ├── index.ts # Barrel export for all operations +│ │ ├── common/ # Shared utilities and infrastructure +│ │ │ ├── descriptions.ts # Centralized parameter descriptions +│ │ │ ├── imports.ts # Common imports barrel for operations +│ │ │ └── utils.ts # DRY utilities and request handlers +│ │ ├── controls.ts # Control-related operations +│ │ ├── vendors.ts # Vendor-related operations +│ │ ├── people.ts # People-related operations +│ │ ├── documents.ts # Document-related operations +│ │ ├── frameworks.ts # Framework-related operations +│ │ ├── risks.ts # Risk scenario operations +│ │ ├── tests.ts # Test-related operations +│ │ ├── trust-centers.ts # Trust Center operations +│ │ └── ... # Other resource operations (17 total) +│ ├── eval/ # Evaluation and testing framework +│ │ ├── eval.ts # LLM evaluation test cases +│ │ └── README.md # Evaluation documentation +│ ├── api.ts # Base API configuration +│ ├── auth.ts # Authentication handling +│ ├── index.ts # Main server entry point +│ ├── registry.ts # Automated tool registration +│ └── types.ts # Type definitions +├── build/ # Compiled JavaScript output +└── README.md # This file +``` + +### Architecture Highlights + +- **Clean Organization**: Operations files are cleanly separated from infrastructure code +- **Common Subdirectory**: All shared utilities, imports, and descriptions are organized in `operations/common/` +- **Automated Registry**: New tools are automatically discovered and registered without manual configuration +- **DRY Principles**: Extensive code reuse through centralized utilities and schema factories +- **Type Safety**: Full TypeScript coverage with comprehensive type definitions + +For detailed architecture documentation, see [`src/operations/README.md`](src/operations/README.md). + ## Debugging You can use the MCP Inspector to debug the server: diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 86aee8a..692c9cd 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -1,58 +1,62 @@ import OpenAI from "openai"; import { zodToJsonSchema } from "zod-to-json-schema"; -import { ListTestsTool, ListTestEntitiesTool } from "../operations/tests.js"; import { + // Tests + ListTestsTool, + ListTestEntitiesTool, + // Frameworks ListFrameworksTool, ListFrameworkControlsTool, GetFrameworkTool, -} from "../operations/frameworks.js"; -import { + // Controls ListControlsTool, ListControlTestsTool, ListLibraryControlsTool, ListControlDocumentsTool, GetControlTool, -} from "../operations/controls.js"; -import { ListRisksTool, GetRiskTool } from "../operations/risks.js"; -import { + // Risks + ListRisksTool, + GetRiskTool, + // Integrations ListIntegrationsTool, GetIntegrationTool, -} from "../operations/integrations.js"; -import { ListVendorsTool, GetVendorTool } from "../operations/vendors.js"; -import { + // Vendors + ListVendorsTool, + GetVendorTool, + // Documents ListDocumentsTool, GetDocumentTool, ListDocumentControlsTool, ListDocumentLinksTool, ListDocumentUploadsTool, DownloadDocumentFileTool, -} from "../operations/documents.js"; -import { ListPoliciesTool, GetPolicyTool } from "../operations/policies.js"; -import { + // Policies + ListPoliciesTool, + GetPolicyTool, + // Discovered Vendors ListDiscoveredVendorsTool, ListDiscoveredVendorAccountsTool, -} from "../operations/discovered-vendors.js"; -import { + // Groups ListGroupsTool, GetGroupTool, ListGroupPeopleTool, -} from "../operations/groups.js"; -import { ListPeopleTool, GetPersonTool } from "../operations/people.js"; -import { + // People + ListPeopleTool, + GetPersonTool, + // Vulnerabilities ListVulnerabilitiesTool, GetVulnerabilityTool, -} from "../operations/vulnerabilities.js"; -import { ListVulnerabilityRemediationsTool } from "../operations/vulnerability-remediations.js"; -import { + // Vulnerability Remediations + ListVulnerabilityRemediationsTool, + // Vulnerable Assets ListVulnerableAssetsTool, GetVulnerableAssetTool, -} from "../operations/vulnerable-assets.js"; -import { + // Monitored Computers ListMonitoredComputersTool, GetMonitoredComputerTool, -} from "../operations/monitored-computers.js"; -import { ListVendorRiskAttributesTool } from "../operations/vendor-risk-attributes.js"; -import { + // Vendor Risk Attributes + ListVendorRiskAttributesTool, + // Trust Centers GetTrustCenterTool, ListTrustCenterAccessRequestsTool, GetTrustCenterAccessRequestTool, @@ -77,7 +81,7 @@ import { ListTrustCenterSubscriberGroupsTool, ListTrustCenterHistoricalAccessRequestsTool, ListTrustCenterSubscribersTool, -} from "../operations/trust-centers.js"; +} from "../operations/index.js"; // Format all tools for OpenAI const tools = [ diff --git a/src/operations/README.md b/src/operations/README.md index 6264b92..d43fd40 100644 --- a/src/operations/README.md +++ b/src/operations/README.md @@ -33,8 +33,11 @@ The operations layer provides a clean, consistent interface to the Vanta API. Ea ``` operations/ ├── README.md # This file -├── global-descriptions.ts # Centralized parameter descriptions -├── utils.ts # DRY utilities and common functions +├── index.ts # Barrel export for all operations +├── common/ # Shared utilities and common files +│ ├── descriptions.ts # Centralized parameter descriptions +│ ├── imports.ts # Centralized common imports for operations +│ └── utils.ts # DRY utilities and common functions ├── controls.ts # Control-related operations ├── vendors.ts # Vendor-related operations ├── people.ts # People-related operations @@ -51,7 +54,7 @@ import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; import { Tool } from "../types.js"; import { z } from "zod"; import { list of DRY utilities } from "./utils.js"; -import { descriptions } from "./global-descriptions.js"; +// This is now available through common-imports.js // 2. Input Schemas (using schema factories) const ListResourcesInput = createPaginationSchema(); @@ -110,6 +113,74 @@ export async function getControl(args: z.infer): Promise ## DRY Utilities +### Barrel Export Pattern + +**Location**: `src/operations/index.ts` + +We use a barrel export pattern to provide a single entry point for importing all tools and utilities: + +```typescript +// Single import for all operations tools +import { + ListControlsTool, + GetControlTool, + ListRisksTool, + // ... all other tools +} from "./operations/index.js"; + +// Instead of multiple individual imports: +// import { ListControlsTool } from "./operations/controls.js"; +// import { ListRisksTool } from "./operations/risks.js"; +// ... dozens more import statements +``` + +**Benefits:** + +- ✅ Single source of truth for operations exports +- ✅ Better organization with commented sections +- ✅ Easier refactoring and maintenance +- ✅ Auto-completion works seamlessly + +### Common Imports Pattern + +**Location**: `src/operations/common/imports.ts` + +For operations files themselves, we use a common imports barrel to reduce repetitive import statements: + +```typescript +// Before: Multiple separate imports in each operations file +import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +import { Tool } from "../types.js"; +import { z } from "zod"; +import { + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./utils.js"; + +// After: Single consolidated import +import { + CallToolResult, + Tool, + z, + createPaginationSchema, + createIdSchema, + makePaginatedGetRequest, + makeGetByIdRequest, +} from "./common/imports.js"; +``` + +**Benefits:** + +- ✅ Reduces import clutter in operations files +- ✅ Ensures consistency across all operations +- ✅ Single source of truth for common dependencies +- ✅ Easier to add new common utilities +- ✅ Better maintainability when dependencies change + +### Utility Functions + The `utils.ts` file provides reusable utilities to eliminate code duplication: ### Response Processing @@ -229,15 +300,18 @@ export async function listResourceDetails( ```typescript // src/operations/new-resource.ts -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; + +// All utilities, descriptions, and core imports are now available +// through the common/imports.js barrel export (located in common/ subdirectory) // Define schemas const ListNewResourcesInput = createPaginationSchema(); @@ -281,7 +355,27 @@ export default { }; ``` -### Step 2: Verify Registry Export +### Step 2: Add to Barrel Export + +Update `src/operations/index.ts` to include your new operations file: + +```typescript +// Add your new operations file to the barrel export +export * from "./tests.js"; +export * from "./frameworks.js"; +export * from "./controls.js"; +// ... existing exports ... +export * from "./new-resource.js"; // ← Add this line + +// Common utilities and shared resources +export * from "./common/utils.js"; +export * from "./common/descriptions.js"; +export * from "./common/imports.js"; +``` + +This ensures your tools are available through the centralized import pattern. + +### Step 3: Verify Registry Export Ensure your operations file includes the required registry export: @@ -298,14 +392,15 @@ export default { **That's it!** Your tools will be automatically registered when the server starts. No changes to `index.ts` are needed. -### Step 3: Add to eval.ts +### Step 4: Add to eval.ts ```typescript -// Import tools +// Import tools from barrel export import { + // ... existing tools ListNewResourcesTool, GetNewResourceTool, -} from "../operations/new-resource.js"; +} from "../operations/index.js"; // Add to tools array const tools = [ @@ -322,7 +417,7 @@ const tools = [ ]; ``` -### Step 4: Update README.md +### Step 5: Update README.md Add the new operations to the main project README.md. @@ -365,7 +460,7 @@ const GetControlInput = z.object({ ```typescript // ✅ Good - Uses centralized description -import { CONTROL_ID_DESCRIPTION } from "./global-descriptions.js"; +import { CONTROL_ID_DESCRIPTION } from "./common/imports.js"; const schema = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); // ❌ Bad - Hardcoded description @@ -580,4 +675,29 @@ await registerAllOperations(server); --- +### Common Files Organization + +The operations directory uses a clean separation between individual operations and shared infrastructure: + +**Operations Files** (at root level): + +- Individual operation files (`controls.ts`, `vendors.ts`, `people.ts`, etc.) +- Each implements tools for a specific Vanta API resource +- Clean, focused implementation with consistent patterns + +**Common Infrastructure** (in `common/` subdirectory): + +- **`descriptions.ts`**: Centralized parameter descriptions for consistency +- **`imports.ts`**: Common imports barrel to reduce import boilerplate +- **`utils.ts`**: DRY utilities including schema factories and request handlers + +**Coordination Files**: + +- **`index.ts`**: Barrel export providing access to all operations from a single import +- **`README.md`**: Architecture documentation (this file) + +This structure provides excellent visual separation between business logic (operations) and infrastructure (common utilities). + +--- + This architecture provides a maintainable, consistent, and **highly scalable** foundation for extending the Vanta MCP Server with new operations while ensuring code quality and developer productivity. The automated registry system ensures that adding new functionality is effortless and error-free! diff --git a/src/operations/global-descriptions.ts b/src/operations/common/descriptions.ts similarity index 83% rename from src/operations/global-descriptions.ts rename to src/operations/common/descriptions.ts index 70ba9f7..ae23029 100644 --- a/src/operations/global-descriptions.ts +++ b/src/operations/common/descriptions.ts @@ -1,23 +1,27 @@ +// Common parameter descriptions used across operations +// This file provides centralized, consistent descriptions for commonly used parameters +// across all operations files, ensuring uniformity and maintainability. + export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of tests returned in a single response. Allowed values: 1–100. Default is 10.`; export const PAGE_CURSOR_DESCRIPTION = `A marker or pointer telling the API where to start fetching items for the subsequent page in a paginated response. Leave blank to start from the first page.`; +export const DOCUMENT_ID_DESCRIPTION = + "Document ID to operate on, e.g. 'document-123' or specific document identifier"; + +export const SLUG_ID_DESCRIPTION = + "Slug ID to operate on, e.g. 'my-trust-center' or specific slug identifier"; + export const CONTROL_ID_DESCRIPTION = "Control ID to operate on, e.g. 'control-123' or specific control identifier"; export const FRAMEWORK_ID_DESCRIPTION = "Framework ID to operate on, e.g. 'framework-123' or specific framework identifier"; -export const DOCUMENT_ID_DESCRIPTION = - "Document ID to operate on, e.g. 'document-123' or specific document identifier"; - export const INTEGRATION_ID_DESCRIPTION = "Integration ID to operate on, e.g. 'integration-123' or specific integration identifier"; -export const SLUG_ID_DESCRIPTION = - "Slug ID to operate on, e.g. 'my-trust-center' or specific slug identifier"; - export const VENDOR_ID_DESCRIPTION = "Vendor ID to operate on, e.g. 'vendor-123' or specific vendor identifier"; diff --git a/src/operations/common/imports.ts b/src/operations/common/imports.ts new file mode 100644 index 0000000..3372ea1 --- /dev/null +++ b/src/operations/common/imports.ts @@ -0,0 +1,14 @@ +// Common imports barrel export for operations files +// This file provides all the common imports that operations files need, +// reducing import clutter and ensuring consistency across the codebase. + +// Core MCP and type imports +export { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; +export { Tool } from "../../types.js"; +export { z } from "zod"; + +// Re-export all utilities +export * from "./utils.js"; + +// Re-export all common descriptions +export * from "./descriptions.js"; diff --git a/src/operations/utils.ts b/src/operations/common/utils.ts similarity index 97% rename from src/operations/utils.ts rename to src/operations/common/utils.ts index 793a91f..3f93fea 100644 --- a/src/operations/utils.ts +++ b/src/operations/common/utils.ts @@ -1,11 +1,11 @@ -import { getValidToken, refreshToken } from "../auth.js"; +import { getValidToken, refreshToken } from "../../auth.js"; import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; import { z } from "zod"; -import { baseApiUrl } from "../api.js"; +import { baseApiUrl } from "../../api.js"; import { PAGE_SIZE_DESCRIPTION, PAGE_CURSOR_DESCRIPTION, -} from "./global-descriptions.js"; +} from "./descriptions.js"; export async function createAuthHeaders(): Promise> { const token = await getValidToken(); diff --git a/src/operations/controls.ts b/src/operations/controls.ts index dd9dbe6..acaec50 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, createIdWithPaginationSchema, @@ -11,8 +11,8 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; -import { CONTROL_ID_DESCRIPTION } from "./global-descriptions.js"; + CONTROL_ID_DESCRIPTION, +} from "./common/imports.js"; // 2. Input Schemas const ListControlsInput = createPaginationSchema().extend({ diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts index 4aad23d..f6de368 100644 --- a/src/operations/discovered-vendors.ts +++ b/src/operations/discovered-vendors.ts @@ -1,15 +1,15 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdWithPaginationSchema, makePaginatedGetRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListDiscoveredVendorsInput = createPaginationSchema(); diff --git a/src/operations/documents.ts b/src/operations/documents.ts index 1a27930..3cb91d7 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, createIdWithPaginationSchema, @@ -11,8 +11,8 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; -import { DOCUMENT_ID_DESCRIPTION } from "./global-descriptions.js"; + DOCUMENT_ID_DESCRIPTION, +} from "./common/imports.js"; // 2. Input Schemas const ListDocumentsInput = createPaginationSchema(); diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index d096a9b..b0310f2 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, createIdWithPaginationSchema, @@ -11,8 +11,8 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; -import { FRAMEWORK_ID_DESCRIPTION } from "./global-descriptions.js"; + FRAMEWORK_ID_DESCRIPTION, +} from "./common/imports.js"; // 2. Input Schemas const ListFrameworksInput = createPaginationSchema(); diff --git a/src/operations/groups.ts b/src/operations/groups.ts index 691b2c2..2433b32 100644 --- a/src/operations/groups.ts +++ b/src/operations/groups.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, createIdWithPaginationSchema, @@ -11,7 +11,7 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListGroupsInput = createPaginationSchema(); diff --git a/src/operations/index.ts b/src/operations/index.ts new file mode 100644 index 0000000..f5315fd --- /dev/null +++ b/src/operations/index.ts @@ -0,0 +1,27 @@ +// Barrel export for all Vanta MCP operations +// This file provides a single entry point for importing any operation tools +// from the Vanta MCP Server operations module. + +// Individual operation modules +export * from "./tests.js"; +export * from "./frameworks.js"; +export * from "./controls.js"; +export * from "./risks.js"; +export * from "./integrations.js"; +export * from "./vendors.js"; +export * from "./documents.js"; +export * from "./policies.js"; +export * from "./discovered-vendors.js"; +export * from "./groups.js"; +export * from "./people.js"; +export * from "./vulnerabilities.js"; +export * from "./vulnerability-remediations.js"; +export * from "./vulnerable-assets.js"; +export * from "./monitored-computers.js"; +export * from "./vendor-risk-attributes.js"; +export * from "./trust-centers.js"; + +// Common utilities and shared resources +export * from "./common/utils.js"; +export * from "./common/descriptions.js"; +export * from "./common/imports.js"; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index 59c7c9b..354acda 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, @@ -10,8 +10,8 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; -import { INTEGRATION_ID_DESCRIPTION } from "./global-descriptions.js"; + INTEGRATION_ID_DESCRIPTION, +} from "./common/imports.js"; // 2. Input Schemas const ListIntegrationsInput = createPaginationSchema(); diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts index 1767087..e2b50af 100644 --- a/src/operations/monitored-computers.ts +++ b/src/operations/monitored-computers.ts @@ -1,13 +1,13 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListMonitoredComputersInput = createPaginationSchema(); diff --git a/src/operations/people.ts b/src/operations/people.ts index 6990e0c..1cf81e4 100644 --- a/src/operations/people.ts +++ b/src/operations/people.ts @@ -1,13 +1,13 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListPeopleInput = createPaginationSchema(); diff --git a/src/operations/policies.ts b/src/operations/policies.ts index 2ca181e..09f9b2e 100644 --- a/src/operations/policies.ts +++ b/src/operations/policies.ts @@ -1,13 +1,13 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListPoliciesInput = createPaginationSchema(); diff --git a/src/operations/risks.ts b/src/operations/risks.ts index 723caf7..1fc43a9 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -1,13 +1,13 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createFilterSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListRisksInput = createFilterSchema({ diff --git a/src/operations/tests.ts b/src/operations/tests.ts index 91f191b..dd18f05 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, createIdWithPaginationSchema, @@ -11,7 +11,7 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListTestEntitiesInput = createIdWithPaginationSchema({ diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts index bea0c11..2a6e48a 100644 --- a/src/operations/trust-centers.ts +++ b/src/operations/trust-centers.ts @@ -1,16 +1,16 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createIdSchema, createIdWithPaginationSchema, makeGetByIdRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; -import { SLUG_ID_DESCRIPTION } from "./global-descriptions.js"; + SLUG_ID_DESCRIPTION, +} from "./common/imports.js"; // 2. Input Schemas const GetTrustCenterInput = createIdSchema({ diff --git a/src/operations/vendor-risk-attributes.ts b/src/operations/vendor-risk-attributes.ts index ee3b454..36536c8 100644 --- a/src/operations/vendor-risk-attributes.ts +++ b/src/operations/vendor-risk-attributes.ts @@ -1,8 +1,11 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; -import { createPaginationSchema, makePaginatedGetRequest } from "./utils.js"; +import { + CallToolResult, + Tool, + z, + createPaginationSchema, + makePaginatedGetRequest, +} from "./common/imports.js"; // 2. Input Schemas const ListVendorRiskAttributesInput = createPaginationSchema(); diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index b4fb2d9..36d0282 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -1,8 +1,8 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, createIdWithPaginationSchema, @@ -11,8 +11,8 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, -} from "./utils.js"; -import { VENDOR_ID_DESCRIPTION } from "./global-descriptions.js"; + VENDOR_ID_DESCRIPTION, +} from "./common/imports.js"; // 2. Input Schemas const ListVendorsInput = createPaginationSchema(); diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index a7db103..040dc0d 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -1,13 +1,13 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListVulnerabilitiesInput = createPaginationSchema(); diff --git a/src/operations/vulnerability-remediations.ts b/src/operations/vulnerability-remediations.ts index 6933e04..5e1bf92 100644 --- a/src/operations/vulnerability-remediations.ts +++ b/src/operations/vulnerability-remediations.ts @@ -1,8 +1,11 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; -import { createPaginationSchema, makePaginatedGetRequest } from "./utils.js"; +import { + CallToolResult, + Tool, + z, + createPaginationSchema, + makePaginatedGetRequest, +} from "./common/imports.js"; // 2. Input Schemas const ListVulnerabilityRemediationsInput = createPaginationSchema(); diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts index dd3c202..3245a1e 100644 --- a/src/operations/vulnerable-assets.ts +++ b/src/operations/vulnerable-assets.ts @@ -1,13 +1,13 @@ // 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; import { + CallToolResult, + Tool, + z, createPaginationSchema, createIdSchema, makePaginatedGetRequest, makeGetByIdRequest, -} from "./utils.js"; +} from "./common/imports.js"; // 2. Input Schemas const ListVulnerableAssetsInput = createPaginationSchema(); From fc63d3d74ea66818424a183b9ebd86b30e1e925f Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Thu, 25 Sep 2025 11:40:50 -0400 Subject: [PATCH 21/24] Refactor to consolidate get and list tools where possible --- README.md | 190 +++--- src/eval/README.md | 153 +++-- src/eval/eval.ts | 829 +++++++------------------- src/operations/README.md | 29 +- src/operations/common/utils.ts | 251 +++++--- src/operations/controls.ts | 76 ++- src/operations/documents.ts | 73 +-- src/operations/frameworks.ts | 51 +- src/operations/groups.ts | 43 +- src/operations/integrations.ts | 75 ++- src/operations/monitored-computers.ts | 54 +- src/operations/people.ts | 43 +- src/operations/policies.ts | 43 +- src/operations/risks.ts | 67 +-- src/operations/tests.ts | 59 +- src/operations/trust-centers.ts | 523 +++++----------- src/operations/vendors.ts | 66 +- src/operations/vulnerabilities.ts | 47 +- src/operations/vulnerable-assets.ts | 48 +- 19 files changed, 1047 insertions(+), 1673 deletions(-) diff --git a/README.md b/README.md index f89a28c..14fa840 100644 --- a/README.md +++ b/README.md @@ -17,11 +17,11 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. | +| [`controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. | | [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Returns test details, current status, and any failing entities for the control's tests. | | [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. | | [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. | -| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. | +| [`controls`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. | ### Discovered Vendors @@ -46,8 +46,8 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. | -| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. | +| [`documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. | +| [`documents`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. | | [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. | | [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. | | [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. | @@ -62,9 +62,9 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. | +| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. | | [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. | -| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. | +| [`frameworks`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. | ### Groups @@ -74,8 +74,8 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. | -| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. | +| [`groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. | +| [`groups`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. | | [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. | ### Integrations @@ -89,14 +89,14 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all infrastructure resources discovered by integrations - Access detailed resource information including metadata, compliance status, and configuration -| Tool Name | Description | -| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist. | -| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. | -| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. | -| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. | -| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. | -| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. | +| Tool Name | Description | +| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist. | +| [`integrations`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. | +| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. | +| [`integrations_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. | +| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. | +| [`integrations_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. | ### Monitored Computers @@ -104,10 +104,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access detailed computer information including hostnames, operating systems, and security status - Manage endpoint security and compliance across diverse computing environments -| Tool Name | Description | -| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. | -| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. | +| [`monitored_computers`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. | ### People @@ -115,10 +115,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access detailed person information including roles, email addresses, and group memberships - Manage organizational structure and access control through comprehensive people data -| Tool Name | Description | -| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. | -| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. | +| [`people`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. | ### Policies @@ -127,10 +127,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Access organizational policies for security, privacy, and operational governance - View policy metadata including names, types, and associated compliance frameworks -| Tool Name | Description | -| --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. | -| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. | +| Tool Name | Description | +| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | +| [`policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. | +| [`policies`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. | ### Risks @@ -138,10 +138,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more - Filterable by risk category (Access Control, Cryptography, Privacy, and many others) -| Tool Name | Description | -| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. | -| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. | +| [`risks`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. | ### Tests @@ -170,27 +170,27 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | -| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | -| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | +| [`trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | +| [`trust_center_access_requests`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | | [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | -| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | -| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | -| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | -| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | -| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | -| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | +| [`trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | +| [`trust_center_control_categories`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | +| [`trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | +| [`trust_center_controls`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | +| [`trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | +| [`trust_center_faqs`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | | [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | | [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | | [`get_trust_center_resource_media`](https://developer.vanta.com/reference/gettrustcenterresourcemedia) | Download Trust Center document media. Get the actual uploaded document/media file for a Trust Center resource for review or audit purposes. | -| [`list_trust_center_subprocessors`](https://developer.vanta.com/reference/listtrustcentersubprocessors) | List Trust Center subprocessors. Get all subprocessors displayed in a specific Trust Center for third-party service provider transparency. | -| [`get_trust_center_subprocessor`](https://developer.vanta.com/reference/gettrustcentersubprocessor) | Get Trust Center subprocessor by ID. Retrieve detailed information about a specific subprocessor including compliance details and certifications. | -| [`list_trust_center_updates`](https://developer.vanta.com/reference/listtrustcenterupdates) | List Trust Center updates. Get all updates and announcements published in a specific Trust Center for compliance status changes and notifications. | -| [`get_trust_center_update`](https://developer.vanta.com/reference/gettrustcenterupdate) | Get Trust Center update by ID. Retrieve detailed information about a specific update including content, publication date, and compliance impact. | -| [`list_trust_center_viewers`](https://developer.vanta.com/reference/listtrustcenterviewers) | List Trust Center viewers. Get all users who have access to view a specific Trust Center for access management and audit purposes. | -| [`get_trust_center_viewer`](https://developer.vanta.com/reference/gettrustcenterviewer) | Get Trust Center viewer by ID. Retrieve detailed information about a specific viewer including access permissions and activity history. | +| [`trust_center_subprocessors`](https://developer.vanta.com/reference/listtrustcentersubprocessors) | List Trust Center subprocessors. Get all subprocessors displayed in a specific Trust Center for third-party service provider transparency. | +| [`trust_center_subprocessors`](https://developer.vanta.com/reference/gettrustcentersubprocessor) | Get Trust Center subprocessor by ID. Retrieve detailed information about a specific subprocessor including compliance details and certifications. | +| [`trust_center_updates`](https://developer.vanta.com/reference/listtrustcenterupdates) | List Trust Center updates. Get all updates and announcements published in a specific Trust Center for compliance status changes and notifications. | +| [`trust_center_updates`](https://developer.vanta.com/reference/gettrustcenterupdate) | Get Trust Center update by ID. Retrieve detailed information about a specific update including content, publication date, and compliance impact. | +| [`trust_center_viewers`](https://developer.vanta.com/reference/listtrustcenterviewers) | List Trust Center viewers. Get all users who have access to view a specific Trust Center for access management and audit purposes. | +| [`trust_center_viewers`](https://developer.vanta.com/reference/gettrustcenterviewer) | Get Trust Center viewer by ID. Retrieve detailed information about a specific viewer including access permissions and activity history. | | [`get_trust_center_subscriber`](https://developer.vanta.com/reference/gettrustcentersubscriber) | Get Trust Center subscriber by ID. Retrieve detailed information about a specific subscriber including subscription preferences and notification settings. | -| [`get_trust_center_subscriber_group`](https://developer.vanta.com/reference/gettrustcentersubscribergroup) | Get Trust Center subscriber group by ID. Retrieve detailed information about a specific subscriber group including members and notification preferences. | -| [`list_trust_center_subscriber_groups`](https://developer.vanta.com/reference/listtrustcentersubscribergroups) | List Trust Center subscriber groups. Get all subscriber groups configured for a specific Trust Center for notification group management. | +| [`trust_center_subscriber_groups`](https://developer.vanta.com/reference/gettrustcentersubscribergroup) | Get Trust Center subscriber group by ID. Retrieve detailed information about a specific subscriber group including members and notification preferences. | +| [`trust_center_subscriber_groups`](https://developer.vanta.com/reference/listtrustcentersubscribergroups) | List Trust Center subscriber groups. Get all subscriber groups configured for a specific Trust Center for notification group management. | | [`list_trust_center_historical_access_requests`](https://developer.vanta.com/reference/listtrustcenterhistoricalaccessrequests) | List Trust Center historical access requests. Get all past access requests for a specific Trust Center for audit and compliance tracking. | | [`list_trust_center_subscribers`](https://developer.vanta.com/reference/listtrustcentersubscribers) | List Trust Center subscribers. Get all subscribers to a specific Trust Center for update notifications and communication management. | @@ -218,12 +218,12 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | Tool Name | Description | | ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. | -| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. | +| [`vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. | +| [`vendors`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. | | [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. | | [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. | | [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. | -| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. | +| [`vendors_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. | | [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. | ### Vulnerabilities @@ -231,10 +231,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Monitor all vulnerabilities detected across your infrastructure and applications - Access detailed vulnerability information including CVE data, severity levels, and affected assets -| Tool Name | Description | -| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. | -| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. | +| [`vulnerabilities`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. | ### Vulnerability Remediations @@ -250,10 +250,10 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - Identify vulnerable assets and understand their security status - Prioritize security efforts based on asset vulnerability associations and risk levels -| Tool Name | Description | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. | -| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. | +| Tool Name | Description | +| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. | +| [`vulnerable_assets`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. | ### Multi-Region Support @@ -267,62 +267,62 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid | [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | | [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | | [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | -| [`list_frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | +| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | | [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | -| [`get_framework`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | -| [`list_controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | +| [`frameworks`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | +| [`controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | | [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | -| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from list_controls which lists controls already in your account - this shows available controls you can implement. | +| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from controls which lists controls already in your account - this shows available controls you can implement. | | [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | -| [`get_control`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from list_controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | -| [`list_risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | -| [`get_risk`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from list_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | -| [`list_integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | -| [`get_integration`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from list_integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | +| [`controls`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | +| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | +| [`risks`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | +| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | +| [`integrations`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | | [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | -| [`get_integration_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | +| [`integrations_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | | [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | -| [`get_integration_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | -| [`list_vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | -| [`get_vendor`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from list_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | +| [`integrations_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | +| [`vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | +| [`vendors`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | | [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | | [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | | [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | -| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | +| [`vendors_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | | [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | -| [`list_documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | -| [`get_document`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from list_documents response. Returns complete document details including name, type, metadata, and compliance mappings. | +| [`documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | +| [`documents`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from documents response. Returns complete document details including name, type, metadata, and compliance mappings. | | [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | | [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | | [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | | [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | -| [`list_policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | -| [`get_policy`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from list_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | +| [`policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | +| [`policies`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | | [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | | [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | -| [`list_groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | -| [`get_group`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from list_groups response. Returns complete group details including name, description, member count, and access permissions. | +| [`groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | +| [`groups`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from groups response. Returns complete group details including name, description, member count, and access permissions. | | [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | -| [`list_people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | -| [`get_person`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from list_people response. Returns complete person details including name, email, role, group memberships, and access permissions. | -| [`list_vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | -| [`get_vulnerability`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | +| [`people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | +| [`people`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from people response. Returns complete person details including name, email, role, group memberships, and access permissions. | +| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | +| [`vulnerabilities`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | | [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | -| [`list_vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | -| [`get_vulnerable_asset`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from list_vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | -| [`list_monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | -| [`get_monitored_computer`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from list_monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | +| [`vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | +| [`vulnerable_assets`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | +| [`monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | +| [`monitored_computers`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | | [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | | [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | -| [`list_trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | -| [`get_trust_center_access_request`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | +| [`trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | +| [`trust_center_access_requests`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | | [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | -| [`list_trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | -| [`get_trust_center_control_category`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | -| [`list_trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | -| [`get_trust_center_control`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | -| [`list_trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | -| [`get_trust_center_faq`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | +| [`trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | +| [`trust_center_control_categories`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | +| [`trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | +| [`trust_center_controls`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | +| [`trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | +| [`trust_center_faqs`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | | [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | | [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | diff --git a/src/eval/README.md b/src/eval/README.md index f57fa5c..c9906a7 100644 --- a/src/eval/README.md +++ b/src/eval/README.md @@ -44,58 +44,71 @@ The evaluation includes 66 test cases covering: ### ✅ **Tool Selection Tests** -- **AWS Security Review**: `list_tests` with AWS and NEEDS_ATTENTION filters -- **SOC2 Compliance**: `list_tests` with SOC2 framework filter -- **Entity Details**: `list_test_entities` for specific failing resources -- **Framework Listing**: `list_frameworks` for available frameworks -- **Control Requirements**: `list_framework_controls` for specific framework details -- **Status Percentage**: `list_frameworks` for completion percentages -- **Control Listing**: `list_controls` for all security controls +- **Framework Listing**: `frameworks` to list available compliance frameworks +- **Framework Details**: `frameworks` with frameworkId for specific framework information +- **Framework Controls**: `list_framework_controls` for control requirements in specific frameworks +- **Control Listing**: `controls` to list all security controls +- **Control Details**: `controls` with controlId for specific control information - **Control Tests**: `list_control_tests` for tests validating specific controls - **Library Controls**: `list_library_controls` for available Vanta library controls - **Control Documents**: `list_control_documents` for documents associated with controls -- **Control Details**: `get_control` for specific control information -- **Framework Details**: `get_framework` for specific framework information -- **Risk Details**: `get_risk` for specific risk scenario information -- **Integration Listing**: `get_integrations` for connected integrations -- **Integration Details**: `get_integration_by_id` for specific integration information -- **Vendor Listing**: `get_vendors` for all vendors -- **Vendor Details**: `get_vendor_by_id` for specific vendor information -- **Document Listing**: `get_documents` for all compliance documents -- **Document Details**: `get_document_by_id` for specific document information -- **Document Controls**: `get_document_controls` for controls associated with documents -- **Document Links**: `get_document_links` for external references in documents -- **Document Uploads**: `get_document_uploads` for file uploads attached to documents +- **Risk Listing**: `risks` to list all risk scenarios +- **Risk Details**: `risks` with riskId for specific risk scenario information +- **Test Listing**: `tests` to list all security tests +- **Test Details**: `tests` with testId for specific test information +- **Test Entities**: `list_test_entities` for resources tested by specific tests +- **Integration Listing**: `integrations` to list connected integrations +- **Integration Details**: `integrations` with integrationId for specific integration information +- **Integration Resource Kinds**: `list_integration_resource_kinds` for available resource types +- **Integration Resource Details**: `get_integration_resource_kind_details` for resource type schemas +- **Integration Resources**: `list_integration_resources` for monitored resources +- **Integration Resource Info**: `get_integration_resource` for specific resource details +- **Vendor Listing**: `vendors` to list all vendors +- **Vendor Details**: `vendors` with vendorId for specific vendor information +- **Vendor Documents**: `list_vendor_documents` for vendor compliance documentation +- **Vendor Findings**: `list_vendor_findings` for vendor security issues +- **Vendor Security Reviews**: `list_vendor_security_reviews` for vendor assessments +- **Vendor Security Review Details**: `get_vendor_security_review` for specific review information +- **Vendor Security Review Documents**: `list_vendor_security_review_documents` for review documentation +- **Document Listing**: `documents` to list all compliance documents +- **Document Details**: `documents` with documentId for specific document information +- **Document Controls**: `list_document_controls` for controls associated with documents +- **Document Links**: `list_document_links` for external references in documents +- **Document Uploads**: `list_document_uploads` for file uploads attached to documents - **Document Downloads**: `download_document_file` for intelligently downloading files (text content for readable files, metadata for binary files) -- **Policy Listing**: `get_policies` for all organizational policies -- **Policy Details**: `get_policy_by_id` for specific policy information -- **Discovered Vendors**: `get_discovered_vendors` for automatically discovered vendors -- **Discovered Vendor Accounts**: `get_discovered_vendor_accounts` for detailed vendor account information -- **Group Listing**: `get_groups` for all organizational groups -- **Group Details**: `get_group_by_id` for specific group information -- **Group Membership**: `get_group_people` for people in specific groups -- **People Listing**: `get_people` for all people in the organization -- **Person Details**: `get_person_by_id` for specific person information -- **Vulnerability Listing**: `get_vulnerabilities` for all detected vulnerabilities -- **Vulnerability Details**: `get_vulnerability_by_id` for specific vulnerability information -- **Vulnerability Remediations**: `get_vulnerability_remediations` for tracking remediation efforts -- **Vulnerable Assets**: `get_vulnerable_assets` for assets affected by vulnerabilities -- **Vulnerable Asset Details**: `get_vulnerable_asset_by_id` for specific asset vulnerability information -- **Monitored Computers**: `get_monitored_computers` for all computers being monitored for compliance -- **Computer Details**: `get_monitored_computer_by_id` for specific computer information -- **Vendor Risk Attributes**: `get_vendor_risk_attributes` for available risk assessment criteria +- **Policy Listing**: `policies` to list all organizational policies +- **Policy Details**: `policies` with policyId for specific policy information +- **Discovered Vendors**: `list_discovered_vendors` for automatically discovered vendors +- **Discovered Vendor Accounts**: `list_discovered_vendor_accounts` for detailed vendor account information +- **Group Listing**: `groups` to list all organizational groups +- **Group Details**: `groups` with groupId for specific group information +- **Group Membership**: `list_group_people` for people in specific groups +- **People Listing**: `people` to list all people in the organization +- **Person Details**: `people` with personId for specific person information +- **Vulnerability Listing**: `vulnerabilities` to list all detected vulnerabilities +- **Vulnerability Details**: `vulnerabilities` with vulnerabilityId for specific vulnerability information +- **Vulnerability Remediations**: `list_vulnerability_remediations` for tracking remediation efforts +- **Vulnerable Assets**: `vulnerable_assets` to list assets affected by vulnerabilities +- **Vulnerable Asset Details**: `vulnerable_assets` with vulnerableAssetId for specific asset vulnerability information +- **Monitored Computers**: `monitored_computers` to list all computers being monitored for compliance +- **Computer Details**: `monitored_computers` with monitoredComputerId for specific computer information +- **Vendor Risk Attributes**: `list_vendor_risk_attributes` for available risk assessment criteria - **Trust Center Configuration**: `get_trust_center` for Trust Center settings and branding -- **Trust Center Access Requests**: `get_trust_center_access_requests` for managing customer access -- **Access Request Details**: `get_trust_center_access_request` for individual request information -- **Trust Center Analytics**: `get_trust_center_viewer_activity_events` for engagement tracking -- **Control Categories**: `get_trust_center_control_categories` for compliance organization -- **Category Details**: `get_trust_center_control_category` for specific category information -- **Published Controls**: `get_trust_center_controls` for public compliance controls -- **Control Details**: `get_trust_center_control` for specific control implementation -- **Trust Center FAQs**: `get_trust_center_faqs` for customer information -- **FAQ Details**: `get_trust_center_faq` for specific FAQ content -- **Trust Center Resources**: `get_trust_center_resources` for downloadable materials +- **Trust Center Access Requests**: `trust_center_access_requests` for managing customer access (list or get specific) +- **Trust Center Analytics**: `list_trust_center_viewer_activity_events` for engagement tracking +- **Control Categories**: `trust_center_control_categories` for compliance organization (list or get specific) +- **Published Controls**: `trust_center_controls` for public compliance controls (list or get specific) +- **Trust Center FAQs**: `trust_center_faqs` for customer information (list or get specific) +- **Trust Center Resources**: `list_trust_center_resources` for downloadable materials - **Resource Documents**: `get_trust_center_document` for specific document details +- **Resource Media**: `get_trust_center_resource_media` for downloading Trust Center files +- **Trust Center Subprocessors**: `trust_center_subprocessors` for third-party service providers (list or get specific) +- **Trust Center Updates**: `trust_center_updates` for compliance status changes (list or get specific) +- **Trust Center Viewers**: `trust_center_viewers` for access management (list or get specific) +- **Trust Center Subscribers**: `get_trust_center_subscriber` for subscriber details +- **Trust Center Subscriber Groups**: `trust_center_subscriber_groups` for subscriber organization (list or get specific) +- **Trust Center Historical Access**: `list_trust_center_historical_access_requests` for audit tracking +- **Trust Center All Subscribers**: `list_trust_center_subscribers` for communication management ### ❌ **Negative Tests** @@ -108,14 +121,20 @@ The evaluation includes 66 test cases covering: 🧪 Vanta MCP Server Tool Evaluation ==================================== -📝 Test: Should call list_tests with AWS filter and NEEDS_ATTENTION status -💬 Prompt: "What security issues do I have in my AWS infrastructure?" -🎯 Expected Tool: list_tests -✅ PASS: Correctly called list_tests +📝 Test: Should call frameworks to list available frameworks +💬 Prompt: "What compliance frameworks are we tracking?" +🎯 Expected Tool: frameworks +✅ PASS: Correctly called frameworks +✅ Parameters match expected values +📋 Called with: {} + +📝 Test: Should call controls with controlId for specific control details +💬 Prompt: "Get details for control ID data-protection-2" +🎯 Expected Tool: controls +✅ PASS: Correctly called controls ✅ Parameters match expected values 📋 Called with: { - "statusFilter": "NEEDS_ATTENTION", - "integrationFilter": "aws" + "controlId": "data-protection-2" } 📊 Final Results @@ -144,6 +163,33 @@ The evaluation includes 66 test cases covering: - No tool was called when one was expected - Tool was called when none should be +## Consolidated Tool Architecture + +The Vanta MCP Server uses a **consolidated tool pattern** where many tools can handle both list and get-by-ID operations: + +### **Consolidated Tools** (53 total) + +These tools accept an optional ID parameter: + +- **Without ID**: Lists all resources with optional filtering and pagination +- **With ID**: Returns the specific resource details + +Examples: + +- `frameworks` - Lists all frameworks OR get specific framework with `frameworkId` +- `controls` - Lists all controls OR get specific control with `controlId` +- `vendors` - Lists all vendors OR get specific vendor with `vendorId` +- `documents` - Lists all documents OR get specific document with `documentId` + +### **Specialized Tools** + +Some tools remain separate for specific operations: + +- `list_control_tests` - Lists tests for a control +- `list_framework_controls` - Lists controls in a framework +- `download_document_file` - Downloads document files +- `get_integration_resource` - Gets specific integration resources + ## Customizing Tests To add new test cases, edit `eval.ts` and add to the `testCases` array: @@ -202,5 +248,6 @@ This evaluation system helps ensure that: - **Real-world prompts** trigger the correct tools - **Parameter passing** works as expected - **Scope boundaries** are respected (no tools called for non-compliance queries) +- **Consolidated architecture** works effectively (LLMs understand optional ID parameters) -The goal is to maintain high confidence that AI assistants will use the Vanta MCP Server correctly for compliance and security management tasks. +The goal is to maintain high confidence that AI assistants will use the Vanta MCP Server correctly for compliance and security management tasks, taking advantage of the intelligent consolidated tool pattern for optimal efficiency. diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 692c9cd..882f974 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -2,83 +2,72 @@ import OpenAI from "openai"; import { zodToJsonSchema } from "zod-to-json-schema"; import { // Tests - ListTestsTool, + TestsTool, ListTestEntitiesTool, // Frameworks - ListFrameworksTool, + FrameworksTool, ListFrameworkControlsTool, - GetFrameworkTool, // Controls - ListControlsTool, + ControlsTool, ListControlTestsTool, ListLibraryControlsTool, ListControlDocumentsTool, - GetControlTool, // Risks - ListRisksTool, - GetRiskTool, + RisksTool, // Integrations - ListIntegrationsTool, - GetIntegrationTool, + IntegrationsTool, + ListIntegrationResourceKindsTool, + GetIntegrationResourceKindDetailsTool, + ListIntegrationResourcesTool, + GetIntegrationResourceTool, // Vendors - ListVendorsTool, - GetVendorTool, + VendorsTool, + ListVendorDocumentsTool, + ListVendorFindingsTool, + ListVendorSecurityReviewsTool, + GetVendorSecurityReviewTool, + ListVendorSecurityReviewDocumentsTool, // Documents - ListDocumentsTool, - GetDocumentTool, + DocumentsTool, ListDocumentControlsTool, ListDocumentLinksTool, ListDocumentUploadsTool, DownloadDocumentFileTool, // Policies - ListPoliciesTool, - GetPolicyTool, + PoliciesTool, // Discovered Vendors ListDiscoveredVendorsTool, ListDiscoveredVendorAccountsTool, // Groups - ListGroupsTool, - GetGroupTool, + GroupsTool, ListGroupPeopleTool, // People - ListPeopleTool, - GetPersonTool, + PeopleTool, // Vulnerabilities - ListVulnerabilitiesTool, - GetVulnerabilityTool, + VulnerabilitiesTool, // Vulnerability Remediations ListVulnerabilityRemediationsTool, // Vulnerable Assets - ListVulnerableAssetsTool, - GetVulnerableAssetTool, + VulnerableAssetsTool, // Monitored Computers - ListMonitoredComputersTool, - GetMonitoredComputerTool, + MonitoredComputersTool, // Vendor Risk Attributes ListVendorRiskAttributesTool, // Trust Centers GetTrustCenterTool, - ListTrustCenterAccessRequestsTool, - GetTrustCenterAccessRequestTool, + TrustCenterAccessRequestsTool, ListTrustCenterViewerActivityEventsTool, - ListTrustCenterControlCategoriesTool, - GetTrustCenterControlCategoryTool, - ListTrustCenterControlsTool, - GetTrustCenterControlTool, - ListTrustCenterFaqsTool, - GetTrustCenterFaqTool, + TrustCenterControlCategoriesTool, + TrustCenterControlsTool, + TrustCenterFaqsTool, ListTrustCenterResourcesTool, GetTrustCenterDocumentTool, GetTrustCenterResourceMediaTool, - ListTrustCenterSubprocessorsTool, - GetTrustCenterSubprocessorTool, - ListTrustCenterUpdatesTool, - GetTrustCenterUpdateTool, - ListTrustCenterViewersTool, - GetTrustCenterViewerTool, + TrustCenterSubprocessorsTool, + TrustCenterUpdatesTool, + TrustCenterViewersTool, GetTrustCenterSubscriberTool, - GetTrustCenterSubscriberGroupTool, - ListTrustCenterSubscriberGroupsTool, + TrustCenterSubscriberGroupsTool, ListTrustCenterHistoricalAccessRequestsTool, ListTrustCenterSubscribersTool, } from "../operations/index.js"; @@ -88,9 +77,9 @@ const tools = [ { type: "function" as const, function: { - name: ListTestsTool.name, - description: ListTestsTool.description, - parameters: zodToJsonSchema(ListTestsTool.parameters), + name: TestsTool.name, + description: TestsTool.description, + parameters: zodToJsonSchema(TestsTool.parameters), }, }, { @@ -104,9 +93,9 @@ const tools = [ { type: "function" as const, function: { - name: ListFrameworksTool.name, - description: ListFrameworksTool.description, - parameters: zodToJsonSchema(ListFrameworksTool.parameters), + name: FrameworksTool.name, + description: FrameworksTool.description, + parameters: zodToJsonSchema(FrameworksTool.parameters), }, }, { @@ -120,9 +109,9 @@ const tools = [ { type: "function" as const, function: { - name: ListControlsTool.name, - description: ListControlsTool.description, - parameters: zodToJsonSchema(ListControlsTool.parameters), + name: ControlsTool.name, + description: ControlsTool.description, + parameters: zodToJsonSchema(ControlsTool.parameters), }, }, { @@ -152,81 +141,109 @@ const tools = [ { type: "function" as const, function: { - name: GetControlTool.name, - description: GetControlTool.description, - parameters: zodToJsonSchema(GetControlTool.parameters), + name: RisksTool.name, + description: RisksTool.description, + parameters: zodToJsonSchema(RisksTool.parameters), }, }, { type: "function" as const, function: { - name: ListRisksTool.name, - description: ListRisksTool.description, - parameters: zodToJsonSchema(ListRisksTool.parameters), + name: IntegrationsTool.name, + description: IntegrationsTool.description, + parameters: zodToJsonSchema(IntegrationsTool.parameters), }, }, { type: "function" as const, function: { - name: GetRiskTool.name, - description: GetRiskTool.description, - parameters: zodToJsonSchema(GetRiskTool.parameters), + name: ListIntegrationResourceKindsTool.name, + description: ListIntegrationResourceKindsTool.description, + parameters: zodToJsonSchema(ListIntegrationResourceKindsTool.parameters), }, }, { type: "function" as const, function: { - name: GetFrameworkTool.name, - description: GetFrameworkTool.description, - parameters: zodToJsonSchema(GetFrameworkTool.parameters), + name: GetIntegrationResourceKindDetailsTool.name, + description: GetIntegrationResourceKindDetailsTool.description, + parameters: zodToJsonSchema( + GetIntegrationResourceKindDetailsTool.parameters, + ), + }, + }, + { + type: "function" as const, + function: { + name: ListIntegrationResourcesTool.name, + description: ListIntegrationResourcesTool.description, + parameters: zodToJsonSchema(ListIntegrationResourcesTool.parameters), + }, + }, + { + type: "function" as const, + function: { + name: GetIntegrationResourceTool.name, + description: GetIntegrationResourceTool.description, + parameters: zodToJsonSchema(GetIntegrationResourceTool.parameters), }, }, { type: "function" as const, function: { - name: ListIntegrationsTool.name, - description: ListIntegrationsTool.description, - parameters: zodToJsonSchema(ListIntegrationsTool.parameters), + name: VendorsTool.name, + description: VendorsTool.description, + parameters: zodToJsonSchema(VendorsTool.parameters), }, }, { type: "function" as const, function: { - name: GetIntegrationTool.name, - description: GetIntegrationTool.description, - parameters: zodToJsonSchema(GetIntegrationTool.parameters), + name: ListVendorDocumentsTool.name, + description: ListVendorDocumentsTool.description, + parameters: zodToJsonSchema(ListVendorDocumentsTool.parameters), }, }, { type: "function" as const, function: { - name: ListVendorsTool.name, - description: ListVendorsTool.description, - parameters: zodToJsonSchema(ListVendorsTool.parameters), + name: ListVendorFindingsTool.name, + description: ListVendorFindingsTool.description, + parameters: zodToJsonSchema(ListVendorFindingsTool.parameters), }, }, { type: "function" as const, function: { - name: GetVendorTool.name, - description: GetVendorTool.description, - parameters: zodToJsonSchema(GetVendorTool.parameters), + name: ListVendorSecurityReviewsTool.name, + description: ListVendorSecurityReviewsTool.description, + parameters: zodToJsonSchema(ListVendorSecurityReviewsTool.parameters), }, }, { type: "function" as const, function: { - name: ListDocumentsTool.name, - description: ListDocumentsTool.description, - parameters: zodToJsonSchema(ListDocumentsTool.parameters), + name: GetVendorSecurityReviewTool.name, + description: GetVendorSecurityReviewTool.description, + parameters: zodToJsonSchema(GetVendorSecurityReviewTool.parameters), }, }, { type: "function" as const, function: { - name: GetDocumentTool.name, - description: GetDocumentTool.description, - parameters: zodToJsonSchema(GetDocumentTool.parameters), + name: ListVendorSecurityReviewDocumentsTool.name, + description: ListVendorSecurityReviewDocumentsTool.description, + parameters: zodToJsonSchema( + ListVendorSecurityReviewDocumentsTool.parameters, + ), + }, + }, + { + type: "function" as const, + function: { + name: DocumentsTool.name, + description: DocumentsTool.description, + parameters: zodToJsonSchema(DocumentsTool.parameters), }, }, { @@ -264,17 +281,9 @@ const tools = [ { type: "function" as const, function: { - name: ListPoliciesTool.name, - description: ListPoliciesTool.description, - parameters: zodToJsonSchema(ListPoliciesTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetPolicyTool.name, - description: GetPolicyTool.description, - parameters: zodToJsonSchema(GetPolicyTool.parameters), + name: PoliciesTool.name, + description: PoliciesTool.description, + parameters: zodToJsonSchema(PoliciesTool.parameters), }, }, { @@ -296,17 +305,9 @@ const tools = [ { type: "function" as const, function: { - name: ListGroupsTool.name, - description: ListGroupsTool.description, - parameters: zodToJsonSchema(ListGroupsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetGroupTool.name, - description: GetGroupTool.description, - parameters: zodToJsonSchema(GetGroupTool.parameters), + name: GroupsTool.name, + description: GroupsTool.description, + parameters: zodToJsonSchema(GroupsTool.parameters), }, }, { @@ -320,33 +321,17 @@ const tools = [ { type: "function" as const, function: { - name: ListPeopleTool.name, - description: ListPeopleTool.description, - parameters: zodToJsonSchema(ListPeopleTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetPersonTool.name, - description: GetPersonTool.description, - parameters: zodToJsonSchema(GetPersonTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListVulnerabilitiesTool.name, - description: ListVulnerabilitiesTool.description, - parameters: zodToJsonSchema(ListVulnerabilitiesTool.parameters), + name: PeopleTool.name, + description: PeopleTool.description, + parameters: zodToJsonSchema(PeopleTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerabilityTool.name, - description: GetVulnerabilityTool.description, - parameters: zodToJsonSchema(GetVulnerabilityTool.parameters), + name: VulnerabilitiesTool.name, + description: VulnerabilitiesTool.description, + parameters: zodToJsonSchema(VulnerabilitiesTool.parameters), }, }, { @@ -360,33 +345,17 @@ const tools = [ { type: "function" as const, function: { - name: ListVulnerableAssetsTool.name, - description: ListVulnerableAssetsTool.description, - parameters: zodToJsonSchema(ListVulnerableAssetsTool.parameters), + name: VulnerableAssetsTool.name, + description: VulnerableAssetsTool.description, + parameters: zodToJsonSchema(VulnerableAssetsTool.parameters), }, }, { type: "function" as const, function: { - name: GetVulnerableAssetTool.name, - description: GetVulnerableAssetTool.description, - parameters: zodToJsonSchema(GetVulnerableAssetTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListMonitoredComputersTool.name, - description: ListMonitoredComputersTool.description, - parameters: zodToJsonSchema(ListMonitoredComputersTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetMonitoredComputerTool.name, - description: GetMonitoredComputerTool.description, - parameters: zodToJsonSchema(GetMonitoredComputerTool.parameters), + name: MonitoredComputersTool.name, + description: MonitoredComputersTool.description, + parameters: zodToJsonSchema(MonitoredComputersTool.parameters), }, }, { @@ -408,17 +377,9 @@ const tools = [ { type: "function" as const, function: { - name: ListTrustCenterAccessRequestsTool.name, - description: ListTrustCenterAccessRequestsTool.description, - parameters: zodToJsonSchema(ListTrustCenterAccessRequestsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetTrustCenterAccessRequestTool.name, - description: GetTrustCenterAccessRequestTool.description, - parameters: zodToJsonSchema(GetTrustCenterAccessRequestTool.parameters), + name: TrustCenterAccessRequestsTool.name, + description: TrustCenterAccessRequestsTool.description, + parameters: zodToJsonSchema(TrustCenterAccessRequestsTool.parameters), }, }, { @@ -434,51 +395,25 @@ const tools = [ { type: "function" as const, function: { - name: ListTrustCenterControlCategoriesTool.name, - description: ListTrustCenterControlCategoriesTool.description, - parameters: zodToJsonSchema( - ListTrustCenterControlCategoriesTool.parameters, - ), + name: TrustCenterControlCategoriesTool.name, + description: TrustCenterControlCategoriesTool.description, + parameters: zodToJsonSchema(TrustCenterControlCategoriesTool.parameters), }, }, { type: "function" as const, function: { - name: GetTrustCenterControlCategoryTool.name, - description: GetTrustCenterControlCategoryTool.description, - parameters: zodToJsonSchema(GetTrustCenterControlCategoryTool.parameters), + name: TrustCenterControlsTool.name, + description: TrustCenterControlsTool.description, + parameters: zodToJsonSchema(TrustCenterControlsTool.parameters), }, }, { type: "function" as const, function: { - name: ListTrustCenterControlsTool.name, - description: ListTrustCenterControlsTool.description, - parameters: zodToJsonSchema(ListTrustCenterControlsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetTrustCenterControlTool.name, - description: GetTrustCenterControlTool.description, - parameters: zodToJsonSchema(GetTrustCenterControlTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListTrustCenterFaqsTool.name, - description: ListTrustCenterFaqsTool.description, - parameters: zodToJsonSchema(ListTrustCenterFaqsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetTrustCenterFaqTool.name, - description: GetTrustCenterFaqTool.description, - parameters: zodToJsonSchema(GetTrustCenterFaqTool.parameters), + name: TrustCenterFaqsTool.name, + description: TrustCenterFaqsTool.description, + parameters: zodToJsonSchema(TrustCenterFaqsTool.parameters), }, }, { @@ -508,49 +443,25 @@ const tools = [ { type: "function" as const, function: { - name: ListTrustCenterSubprocessorsTool.name, - description: ListTrustCenterSubprocessorsTool.description, - parameters: zodToJsonSchema(ListTrustCenterSubprocessorsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetTrustCenterSubprocessorTool.name, - description: GetTrustCenterSubprocessorTool.description, - parameters: zodToJsonSchema(GetTrustCenterSubprocessorTool.parameters), + name: TrustCenterSubprocessorsTool.name, + description: TrustCenterSubprocessorsTool.description, + parameters: zodToJsonSchema(TrustCenterSubprocessorsTool.parameters), }, }, { type: "function" as const, function: { - name: ListTrustCenterUpdatesTool.name, - description: ListTrustCenterUpdatesTool.description, - parameters: zodToJsonSchema(ListTrustCenterUpdatesTool.parameters), + name: TrustCenterUpdatesTool.name, + description: TrustCenterUpdatesTool.description, + parameters: zodToJsonSchema(TrustCenterUpdatesTool.parameters), }, }, { type: "function" as const, function: { - name: GetTrustCenterUpdateTool.name, - description: GetTrustCenterUpdateTool.description, - parameters: zodToJsonSchema(GetTrustCenterUpdateTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListTrustCenterViewersTool.name, - description: ListTrustCenterViewersTool.description, - parameters: zodToJsonSchema(ListTrustCenterViewersTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetTrustCenterViewerTool.name, - description: GetTrustCenterViewerTool.description, - parameters: zodToJsonSchema(GetTrustCenterViewerTool.parameters), + name: TrustCenterViewersTool.name, + description: TrustCenterViewersTool.description, + parameters: zodToJsonSchema(TrustCenterViewersTool.parameters), }, }, { @@ -564,19 +475,9 @@ const tools = [ { type: "function" as const, function: { - name: GetTrustCenterSubscriberGroupTool.name, - description: GetTrustCenterSubscriberGroupTool.description, - parameters: zodToJsonSchema(GetTrustCenterSubscriberGroupTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListTrustCenterSubscriberGroupsTool.name, - description: ListTrustCenterSubscriberGroupsTool.description, - parameters: zodToJsonSchema( - ListTrustCenterSubscriberGroupsTool.parameters, - ), + name: TrustCenterSubscriberGroupsTool.name, + description: TrustCenterSubscriberGroupsTool.description, + parameters: zodToJsonSchema(TrustCenterSubscriberGroupsTool.parameters), }, }, { @@ -599,499 +500,216 @@ const tools = [ }, ]; -// Test cases with expected tool calls -interface TestCase { - prompt: string; - expectedTool: string; - expectedParams?: Record; - description: string; -} - -const testCases: TestCase[] = [ - { - prompt: "What security issues do I have in my AWS infrastructure?", - expectedTool: "list_tests", - expectedParams: { - statusFilter: "NEEDS_ATTENTION", - integrationFilter: "aws", - }, - description: - "Should call get_tests with AWS filter and NEEDS_ATTENTION status", - }, - { - prompt: "Show me all my SOC2 compliance tests that are failing", - expectedTool: "list_tests", - expectedParams: { - frameworkFilter: "soc2", - statusFilter: "NEEDS_ATTENTION", - }, - description: "Should call get_tests with SOC2 framework filter", - }, - { - prompt: - "Show me the specific failing entities for test ID aws-security-groups-open-to-world", - expectedTool: "list_test_entities", - expectedParams: { testId: "aws-security-groups-open-to-world" }, - description: "Should call get_test_entities for specific test details", - }, - { - prompt: "Show me the details of test ID aws-security-groups-open-to-world", - expectedTool: "get_test", - expectedParams: { testId: "aws-security-groups-open-to-world" }, - description: "Should call get_test_by_id for specific test details", - }, +// Test cases for the LLM evaluation +export const testCases = [ { prompt: "What compliance frameworks are we tracking?", - expectedTool: "list_frameworks", + expectedTool: "frameworks", expectedParams: {}, - description: "Should call get_frameworks to list available frameworks", - }, - { - prompt: "Get the control requirements for framework ID soc2", - expectedTool: "list_framework_controls", - expectedParams: { frameworkId: "soc2" }, - description: "Should call get_framework_controls for SOC2", + description: "Should call frameworks to list available frameworks", }, { prompt: "What is the current % status of my SOC 2?", - expectedTool: "list_frameworks", + expectedTool: "frameworks", expectedParams: {}, - description: "Should call get_frameworks to get SOC2 completion percentage", + description: "Should call frameworks to get SOC2 completion percentage", }, { prompt: "List all security controls in my Vanta account", - expectedTool: "list_controls", + expectedTool: "controls", expectedParams: {}, - description: "Should call get_controls to list all available controls", + description: "Should call controls to list all available controls", }, { - prompt: "Show me the tests for control ID access-control-1", + prompt: + "Show me all automated tests for the access-control-user-provisioning control", expectedTool: "list_control_tests", - expectedParams: { controlId: "access-control-1" }, - description: "Should call get_control_tests for specific control", - }, - { - prompt: "What controls are available in the Vanta library that I can add?", - expectedTool: "list_library_controls", - expectedParams: {}, + expectedParams: { controlId: "access-control-user-provisioning" }, description: - "Should call get_library_controls to list available library controls", - }, - { - prompt: "Show me the documents for control ID access-control-1", - expectedTool: "list_control_documents", - expectedParams: { controlId: "access-control-1" }, - description: "Should call get_control_documents for specific control", + "Should call list_control_tests to get tests for specific control", }, { prompt: "Get details for control ID data-protection-2", - expectedTool: "get_control", + expectedTool: "controls", expectedParams: { controlId: "data-protection-2" }, - description: "Should call get_control_by_id for specific control details", + description: + "Should call controls with controlId for specific control details", }, { prompt: "Show me details for framework ID soc2", - expectedTool: "get_framework", + expectedTool: "frameworks", + expectedParams: { frameworkId: "soc2" }, + description: + "Should call frameworks with frameworkId for SOC2 framework details", + }, + { + prompt: "What controls does the SOC 2 framework require?", + expectedTool: "list_framework_controls", expectedParams: { frameworkId: "soc2" }, description: - "Should call get_framework_by_id for specific framework details", + "Should call list_framework_controls to get SOC2 framework requirements", }, { prompt: "Get details for risk scenario ID risk-scenario-123", - expectedTool: "get_risk", + expectedTool: "risks", expectedParams: { riskId: "risk-scenario-123" }, description: - "Should call get_risk_by_id for specific risk scenario details", + "Should call risks with riskId for specific risk scenario details", + }, + { + prompt: "Show me all risk scenarios categorized as Access Control", + expectedTool: "risks", + expectedParams: { categoryMatchesAny: "Access Control" }, + description: + "Should call risks with category filter for Access Control risks", }, { prompt: "What integrations are connected to my Vanta account?", - expectedTool: "list_integrations", + expectedTool: "integrations", expectedParams: {}, - description: - "Should call get_integrations to list all connected integrations", + description: "Should call integrations to list all connected integrations", }, { prompt: "Show me details for integration ID aws", - expectedTool: "get_integration", + expectedTool: "integrations", expectedParams: { integrationId: "aws" }, description: - "Should call get_integration_by_id for specific integration details", + "Should call integrations with integrationId for AWS integration details", }, { prompt: "List all vendors in my Vanta account", - expectedTool: "list_vendors", + expectedTool: "vendors", expectedParams: {}, - description: "Should call get_vendors to list all vendors", + description: "Should call vendors to list all vendors", }, { prompt: "Get details for vendor ID vendor-123", - expectedTool: "get_vendor", + expectedTool: "vendors", expectedParams: { vendorId: "vendor-123" }, - description: "Should call get_vendor_by_id for specific vendor details", + description: + "Should call vendors with vendorId for specific vendor details", }, { prompt: "Show me all the documents we have uploaded to Vanta for compliance purposes.", - expectedTool: "list_documents", + expectedTool: "documents", expectedParams: {}, - description: "Should call get_documents to list all compliance documents", + description: "Should call documents to list all compliance documents", }, { prompt: "I need to see the details of document DOC-12345 including its metadata and compliance mappings.", - expectedTool: "get_document", + expectedTool: "documents", expectedParams: { documentId: "DOC-12345" }, - description: "Should call get_document_by_id for specific document details", - }, - { - prompt: "Which security controls are mapped to document DOC-789?", - expectedTool: "list_document_controls", - expectedParams: { documentId: "DOC-789" }, description: - "Should call get_document_controls to find controls associated with document", - }, - { - prompt: - "What external links and references are attached to document POLICY-456?", - expectedTool: "list_document_links", - expectedParams: { documentId: "POLICY-456" }, - description: - "Should call get_document_links to get external references for document", - }, - { - prompt: "List all the files uploaded to document SEC-123.", - expectedTool: "list_document_uploads", - expectedParams: { documentId: "SEC-123" }, - description: - "Should call get_document_uploads to list file uploads for document", - }, - { - prompt: - "I need to download the file with uploaded file ID FILE-456 from document DOC-789.", - expectedTool: "download_document_file", - expectedParams: { documentId: "DOC-789", uploadedFileId: "FILE-456" }, - description: - "Should call download_document_file to download specific file from document", + "Should call documents with documentId for specific document details", }, { prompt: "Show me all the policies we have established for our organization.", - expectedTool: "list_policies", + expectedTool: "policies", expectedParams: {}, - description: "Should call get_policies to list all organizational policies", + description: "Should call policies to list all organizational policies", }, { prompt: "I need to review the details of our data retention policy with ID POLICY-789.", - expectedTool: "get_policy", + expectedTool: "policies", expectedParams: { policyId: "POLICY-789" }, - description: "Should call get_policy_by_id for specific policy details", - }, - { - prompt: - "Show me all the vendors that have been discovered through our integrations but aren't yet managed.", - expectedTool: "list_discovered_vendors", - expectedParams: {}, description: - "Should call get_discovered_vendors to list automatically discovered vendors", - }, - { - prompt: - "I need detailed account information for all discovered vendor accounts from our integrations.", - expectedTool: "list_discovered_vendor_accounts", - expectedParams: {}, - description: - "Should call get_discovered_vendor_accounts to get detailed vendor account information", + "Should call policies with policyId for specific policy details", }, { prompt: "Show me all the organizational groups we have set up for access management.", - expectedTool: "list_groups", + expectedTool: "groups", expectedParams: {}, - description: "Should call get_groups to list all organizational groups", + description: "Should call groups to list all organizational groups", }, { prompt: "I need details about the Engineering group with ID GROUP-456.", - expectedTool: "get_group", + expectedTool: "groups", expectedParams: { groupId: "GROUP-456" }, - description: "Should call get_group_by_id for specific group details", - }, - { - prompt: "Who are all the members of the Security team group?", - expectedTool: "list_group_people", - expectedParams: { groupId: "Security team" }, - description: - "Should call get_group_people to list people in a specific group", + description: "Should call groups with groupId for specific group details", }, { prompt: "List all people in our organization for the compliance audit.", - expectedTool: "list_people", + expectedTool: "people", expectedParams: {}, - description: - "Should call get_people to list all people in the organization", + description: "Should call people to list all people in the organization", }, { prompt: "Get me the details for employee PERSON-789.", - expectedTool: "get_person", + expectedTool: "people", expectedParams: { personId: "PERSON-789" }, - description: "Should call get_person_by_id for specific person details", + description: "Should call people with personId for specific person details", }, { prompt: "Show me all the security vulnerabilities detected in our infrastructure.", - expectedTool: "list_vulnerabilities", + expectedTool: "vulnerabilities", expectedParams: {}, description: - "Should call get_vulnerabilities to list all detected vulnerabilities", + "Should call vulnerabilities to list all detected vulnerabilities", }, { prompt: "I need detailed information about vulnerability VULN-456 including its CVE data.", - expectedTool: "get_vulnerability", + expectedTool: "vulnerabilities", expectedParams: { vulnerabilityId: "VULN-456" }, description: - "Should call get_vulnerability_by_id for specific vulnerability details", - }, - { - prompt: "What vulnerability remediations are currently in progress?", - expectedTool: "list_vulnerability_remediations", - expectedParams: {}, - description: - "Should call get_vulnerability_remediations to track remediation efforts", + "Should call vulnerabilities with vulnerabilityId for specific vulnerability details", }, { prompt: "List all assets that are affected by vulnerabilities for our security review.", - expectedTool: "list_vulnerable_assets", + expectedTool: "vulnerable_assets", expectedParams: {}, description: - "Should call get_vulnerable_assets to identify affected infrastructure", + "Should call vulnerable_assets to list all assets affected by vulnerabilities", }, { prompt: "Get details about vulnerable asset ASSET-789 and its security status.", - expectedTool: "get_vulnerable_asset", + expectedTool: "vulnerable_assets", expectedParams: { vulnerableAssetId: "ASSET-789" }, description: - "Should call get_vulnerable_asset_by_id for specific asset vulnerability details", + "Should call vulnerable_assets with vulnerableAssetId for specific asset details", }, { prompt: "Show me all the computers being monitored for compliance across our organization.", - expectedTool: "list_monitored_computers", + expectedTool: "monitored_computers", expectedParams: {}, description: - "Should call get_monitored_computers to list all monitored computers", + "Should call monitored_computers to list all monitored computers", }, { prompt: "I need details about the monitored computer with ID COMP-456.", - expectedTool: "get_monitored_computer", + expectedTool: "monitored_computers", expectedParams: { computerId: "COMP-456" }, description: - "Should call get_monitored_computer_by_id for specific computer details", + "Should call monitored_computers with computerId for specific computer details", }, { - prompt: - "What vendor risk attributes are available for evaluating our vendors?", - expectedTool: "list_vendor_risk_attributes", + prompt: "What are all the security tests currently running in Vanta?", + expectedTool: "tests", expectedParams: {}, - description: - "Should call get_vendor_risk_attributes to list available risk assessment criteria", - }, - { - prompt: - "Show me the configuration and settings for our Trust Center 'acme-security'.", - expectedTool: "get_trust_center", - expectedParams: { slugId: "acme-security" }, - description: - "Should call get_trust_center to get Trust Center configuration details", - }, - { - prompt: "List all pending access requests for our Trust Center.", - expectedTool: "list_trust_center_access_requests", - expectedParams: { slugId: "our-trust-center" }, - description: - "Should call get_trust_center_access_requests to review access requests", + description: "Should call tests to list all security tests", }, { - prompt: "Get details about Trust Center access request REQ-789.", - expectedTool: "get_trust_center_access_request", - expectedParams: { slugId: "trust-center", accessRequestId: "REQ-789" }, - description: - "Should call get_trust_center_access_request for specific request details", - }, - { - prompt: "What viewer activity has occurred on our Trust Center this month?", - expectedTool: "list_trust_center_viewer_activity_events", - expectedParams: { slugId: "our-trust-center" }, - description: - "Should call get_trust_center_viewer_activity_events to track engagement analytics", - }, - { - prompt: "Show me all the control categories in our Trust Center.", - expectedTool: "list_trust_center_control_categories", - expectedParams: { slugId: "trust-center" }, - description: - "Should call get_trust_center_control_categories to list control organization", - }, - { - prompt: "Get details about Trust Center control category CAT-456.", - expectedTool: "get_trust_center_control_category", - expectedParams: { slugId: "trust-center", controlCategoryId: "CAT-456" }, - description: - "Should call get_trust_center_control_category for specific category details", - }, - { - prompt: "List all the controls published in our public Trust Center.", - expectedTool: "list_trust_center_controls", - expectedParams: { slugId: "public-trust-center" }, - description: - "Should call get_trust_center_controls to see published compliance controls", - }, - { - prompt: "Get implementation details for Trust Center control TC-CTRL-123.", - expectedTool: "get_trust_center_control", - expectedParams: { - slugId: "trust-center", - trustCenterControlId: "TC-CTRL-123", - }, - description: - "Should call get_trust_center_control for specific control implementation details", - }, - { - prompt: "What FAQs are available on our Trust Center for customers?", - expectedTool: "list_trust_center_faqs", - expectedParams: { slugId: "customer-trust-center" }, - description: - "Should call get_trust_center_faqs to list customer information", - }, - { - prompt: "Show me the details of FAQ FAQ-789 from our Trust Center.", - expectedTool: "get_trust_center_faq", - expectedParams: { slugId: "trust-center", faqId: "FAQ-789" }, - description: "Should call get_trust_center_faq for specific FAQ content", - }, - { - prompt: - "What compliance documents and resources are available for download on our Trust Center?", - expectedTool: "list_trust_center_resources", - expectedParams: { slugId: "compliance-center" }, - description: - "Should call get_trust_center_resources to list downloadable materials", - }, - { - prompt: - "Get details about the SOC2 report document DOC-456 on our Trust Center.", - expectedTool: "get_trust_center_document", - expectedParams: { - slugId: "trust-center", - resourceId: "DOC-456", - }, - description: - "Should call get_trust_center_document for specific document details", + prompt: "Show me details for test ID TEST-789.", + expectedTool: "tests", + expectedParams: { testId: "TEST-789" }, + description: "Should call tests with testId for specific test details", }, { prompt: - "Download the actual compliance certificate file CERT-123 from our Trust Center.", - expectedTool: "get_trust_center_resource_media", - expectedParams: { slugId: "trust-center", resourceId: "CERT-123" }, - description: - "Should call get_trust_center_resource_media to download document media", - }, - { - prompt: - "List all subprocessors displayed on our Trust Center for customer transparency.", - expectedTool: "list_trust_center_subprocessors", - expectedParams: { slugId: "customer-trust-center" }, - description: - "Should call list_trust_center_subprocessors to list third-party service providers", - }, - { - prompt: - "Get details about subprocessor SUBPROC-789 listed on our Trust Center.", - expectedTool: "get_trust_center_subprocessor", - expectedParams: { slugId: "trust-center", subprocessorId: "SUBPROC-789" }, - description: - "Should call get_trust_center_subprocessor for specific subprocessor information", - }, - { - prompt: - "Show me all the recent updates and announcements on our Trust Center.", - expectedTool: "list_trust_center_updates", - expectedParams: { slugId: "company-trust-center" }, - description: - "Should call list_trust_center_updates to see compliance notifications", - }, - { - prompt: - "Get the details of Trust Center update UPDATE-456 about SOC2 compliance.", - expectedTool: "get_trust_center_update", - expectedParams: { slugId: "trust-center", updateId: "UPDATE-456" }, - description: - "Should call get_trust_center_update for specific update content", - }, - { - prompt: "Who has access to view our Trust Center? List all viewers.", - expectedTool: "list_trust_center_viewers", - expectedParams: { slugId: "private-trust-center" }, - description: "Should call list_trust_center_viewers for access management", - }, - { - prompt: "Get access details for Trust Center viewer USER-123.", - expectedTool: "get_trust_center_viewer", - expectedParams: { slugId: "trust-center", viewerId: "USER-123" }, - description: - "Should call get_trust_center_viewer for specific viewer information", - }, - { - prompt: "Get notification preferences for Trust Center subscriber SUB-789.", - expectedTool: "get_trust_center_subscriber", - expectedParams: { slugId: "trust-center", subscriberId: "SUB-789" }, - description: - "Should call get_trust_center_subscriber for subscriber settings", - }, - { - prompt: "Show me details about Trust Center subscriber group GROUP-456.", - expectedTool: "get_trust_center_subscriber_group", - expectedParams: { slugId: "trust-center", subscriberGroupId: "GROUP-456" }, - description: - "Should call get_trust_center_subscriber_group for group information", - }, - { - prompt: "List all notification groups configured for our Trust Center.", - expectedTool: "list_trust_center_subscriber_groups", - expectedParams: { slugId: "notification-center" }, - description: - "Should call list_trust_center_subscriber_groups for group management", - }, - { - prompt: - "Show me all historical access requests for our Trust Center from last year.", - expectedTool: "list_trust_center_historical_access_requests", - expectedParams: { slugId: "audit-trust-center" }, - description: - "Should call list_trust_center_historical_access_requests for audit tracking", - }, - { - prompt: "List everyone subscribed to updates from our Trust Center.", - expectedTool: "list_trust_center_subscribers", - expectedParams: { slugId: "update-center" }, - description: - "Should call list_trust_center_subscribers for communication management", - }, - { - prompt: "What programming tests should I write for my API?", - expectedTool: "none", - expectedParams: {}, - description: - "Should NOT call any Vanta tools - this is about code testing, not compliance", - }, - { - prompt: "Help me debug this JavaScript function", - expectedTool: "none", - expectedParams: {}, + "What entities are being tested by the test with ID aws-ec2-security-groups?", + expectedTool: "list_test_entities", + expectedParams: { testId: "aws-ec2-security-groups" }, description: - "Should NOT call any Vanta tools - this is about code debugging", + "Should call list_test_entities to get entities for specific test", }, ]; @@ -1140,10 +758,7 @@ for (const testCase of testCases) { console.log(`✅ PASS: Correctly called ${calledTool}`); // Check specific parameters if provided - if ( - testCase.expectedParams && - Object.keys(testCase.expectedParams).length > 0 - ) { + if (Object.keys(testCase.expectedParams).length > 0) { let paramsMatch = true; for (const [key, value] of Object.entries( testCase.expectedParams, @@ -1205,3 +820,5 @@ if (passedTests === totalTests) { "⚠️ Some tests failed. Review the tool descriptions or test cases.", ); } + +export { tools }; diff --git a/src/operations/README.md b/src/operations/README.md index d43fd40..8a265a0 100644 --- a/src/operations/README.md +++ b/src/operations/README.md @@ -22,12 +22,39 @@ The operations layer provides a clean, consistent interface to the Vanta API. Ea ### Key Architectural Principles 1. **DRY (Don't Repeat Yourself)**: Common patterns are abstracted into reusable utilities -2. **RESTful Naming**: Tools follow REST conventions (`list_*` for multiple items, `get_*` for single items) +2. **Consolidated Tool Pattern**: Single tools intelligently handle both list and get operations 3. **Type Safety**: Full TypeScript support with proper type definitions 4. **Consistent Error Handling**: Standardized error responses across all operations 5. **Schema Factories**: Reusable Zod schema generators for common patterns 6. **Automated Registry**: Zero-maintenance tool registration system +### Consolidated Tool Architecture + +The operations layer implements a **consolidated tool pattern** where a single tool can intelligently handle both listing multiple resources and retrieving a single resource by ID. This approach provides significant benefits: + +#### Benefits of Consolidation + +- **Improved LLM Experience**: Reduces cognitive load by providing fewer, more intuitive tools +- **Clearer Intent Mapping**: Tools match natural language patterns ("I want controls" vs "I want to list controls") +- **Reduced API Surface**: Fewer tools to learn, document, and maintain +- **Intelligent Routing**: Single tool automatically routes to appropriate endpoints based on parameters +- **Preserved Functionality**: All original capabilities maintained with enhanced usability + +#### How It Works + +```typescript +// Single tool handles multiple scenarios +await controls({}); // Lists all controls +await controls({ controlId: "control-123" }); // Gets specific control +await controls({ frameworkMatchesAny: ["soc2"] }); // Filtered listing + +// Trust Center tools include required slugId +await trust_center_faqs({ slugId: "company" }); // Lists FAQs +await trust_center_faqs({ slugId: "company", faqId: "faq-123" }); // Gets specific FAQ +``` + +The consolidation pattern uses optional ID parameters - when an ID is provided, the tool retrieves that specific resource; when omitted, it lists all resources with optional filtering and pagination. + ## File Structure ``` diff --git a/src/operations/common/utils.ts b/src/operations/common/utils.ts index 3f93fea..172019e 100644 --- a/src/operations/common/utils.ts +++ b/src/operations/common/utils.ts @@ -18,40 +18,41 @@ export async function createAuthHeaders(): Promise> { /** * Makes an authenticated HTTP request using a bearer token from the Vanta MCP auth system. * If the request returns a 401 Unauthorized, it will refresh the token and retry once. - * - * @param {string} url - The URL to send the request to. - * @param {RequestInit} [options={}] - Optional fetch options (method, headers, body, etc.). - * @returns {Promise} The fetch Response object. */ export async function makeAuthenticatedRequest( url: string, options: RequestInit = {}, ): Promise { - let headers = await createAuthHeaders(); + const headers = await createAuthHeaders(); - const response = await fetch(url, { + const requestOptions: RequestInit = { ...options, headers: { ...headers, ...options.headers, }, - }); + }; - // If we get unauthorized, try refreshing the token once - if (response.status === 401) { - const newToken = await refreshToken(); - headers = { - "Authorization": `Bearer ${newToken}`, - "x-vanta-is-mcp": "true", - }; + // Try the request with the current token + let response = await fetch(url, requestOptions); - return fetch(url, { - ...options, - headers: { - ...headers, - ...options.headers, - }, - }); + // If we get a 401, refresh the token and try again + if (response.status === 401) { + try { + await refreshToken(); + const newHeaders = await createAuthHeaders(); + const retryOptions: RequestInit = { + ...options, + headers: { + ...newHeaders, + ...options.headers, + }, + }; + response = await fetch(url, retryOptions); + } catch (refreshError) { + console.error("Failed to refresh token:", refreshError); + // Return the original 401 response + } } return response; @@ -62,34 +63,35 @@ export async function makeAuthenticatedRequest( // ========================================== /** - * Creates a standard error response for failed API calls + * Creates an error response with consistent formatting */ export function createErrorResponse(statusText: string): CallToolResult { return { - content: [ - { - type: "text" as const, - text: `Error: ${statusText}`, - }, - ], + content: [{ type: "text", text: `Error: ${statusText}` }], + isError: true, }; } /** - * Creates a standard success response with JSON data + * Creates a success response with JSON content */ export async function createSuccessResponse( response: Response, ): Promise { - return { - content: [ - { type: "text" as const, text: JSON.stringify(await response.json()) }, - ], - }; + try { + const jsonData: unknown = await response.json(); + return { + content: [{ type: "text", text: JSON.stringify(jsonData, null, 2) }], + }; + } catch (error) { + return createErrorResponse( + `Failed to parse JSON response: ${error instanceof Error ? error.message : "Unknown error"}`, + ); + } } /** - * Handles API response with standard error/success processing + * Handles API response consistently - either returns success or error */ export async function handleApiResponse( response: Response, @@ -105,59 +107,114 @@ export async function handleApiResponse( // ========================================== /** - * Creates a schema with only pagination parameters + * Creates a standard pagination schema */ -export function createPaginationSchema(): z.ZodObject<{ - pageSize: z.ZodOptional; - pageCursor: z.ZodOptional; -}> { +export function createPaginationSchema( + customFields: Record = {}, +): z.ZodObject> { return z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), + pageSize: z + .number() + .min(1) + .max(100) + .describe(PAGE_SIZE_DESCRIPTION) + .optional(), pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + ...customFields, }); } /** - * Creates a schema with a single ID parameter + * Creates a filter schema with pagination base */ -export function createIdSchema(params: { +export function createFilterSchema( + customFields: Record = {}, +): z.ZodObject> { + return z.object({ + pageSize: z + .number() + .min(1) + .max(100) + .describe(PAGE_SIZE_DESCRIPTION) + .optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), + ...customFields, + }); +} + +/** + * Creates a schema with a single required ID parameter plus pagination + */ +export function createIdWithPaginationSchema(params: { paramName: string; description: string; -}): z.ZodObject> { +}): z.ZodObject> { return z.object({ [params.paramName]: z.string().describe(params.description), + pageSize: z + .number() + .min(1) + .max(100) + .describe(PAGE_SIZE_DESCRIPTION) + .optional(), + pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); } /** - * Creates a schema with an ID parameter plus pagination + * Creates a schema with a single required ID parameter only */ -export function createIdWithPaginationSchema(params: { +export function createIdSchema(params: { paramName: string; description: string; -}): z.ZodObject< - Record< - string, - z.ZodString | z.ZodOptional | z.ZodOptional - > -> { +}): z.ZodObject> { return z.object({ [params.paramName]: z.string().describe(params.description), - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), }); } /** - * Creates a base schema that can be extended with custom fields + * Creates a schema for consolidated tools that can either list resources or get a single resource by ID */ -export function createFilterSchema( - customFields: Record = {}, +export function createConsolidatedSchema( + params: { + paramName: string; + description: string; + resourceName: string; + }, + additionalFields: Record = {}, ): z.ZodObject> { + const idDescription = `Optional ${params.resourceName} ID. If provided, returns the specific ${params.resourceName}. If omitted, lists all ${params.resourceName}s with optional filtering and pagination.`; + return z.object({ - pageSize: z.number().describe(PAGE_SIZE_DESCRIPTION).optional(), - pageCursor: z.string().describe(PAGE_CURSOR_DESCRIPTION).optional(), - ...customFields, + [params.paramName]: z.string().describe(idDescription).optional(), + ...createPaginationSchema().shape, + ...additionalFields, + }); +} + +/** + * Creates a schema for Trust Center consolidated tools that require a slugId plus optional resource ID + */ +export function createTrustCenterConsolidatedSchema( + params: { + paramName: string; + description: string; + resourceName: string; + }, + additionalFields: Record = {}, +): z.ZodObject> { + const idDescription = `Optional ${params.resourceName} ID. If provided, returns the specific ${params.resourceName}. If omitted, lists all ${params.resourceName}s with optional filtering and pagination.`; + + return z.object({ + slugId: z + .string() + .describe( + "Trust Center slug ID, e.g. 'company-trust-center' or specific trust center identifier", + ), + [params.paramName]: z.string().describe(idDescription).optional(), + ...createPaginationSchema().shape, + ...additionalFields, }); } @@ -166,7 +223,7 @@ export function createFilterSchema( // ========================================== /** - * Builds a URL with query parameters from an object + * Builds a URL with query parameters */ export function buildUrl( basePath: string, @@ -174,18 +231,16 @@ export function buildUrl( ): string { const url = new URL(basePath, baseApiUrl()); - Object.entries(params).forEach(([key, value]) => { + for (const [key, value] of Object.entries(params)) { if (value !== undefined) { if (Array.isArray(value)) { - // Handle array parameters (e.g., frameworkMatchesAny) - value.forEach(item => { - url.searchParams.append(key, String(item)); - }); + // Handle arrays by joining with commas + url.searchParams.set(key, value.join(",")); } else { - url.searchParams.append(key, String(value)); + url.searchParams.set(key, String(value)); } } - }); + } return url.toString(); } @@ -195,22 +250,22 @@ export function buildUrl( // ========================================== /** - * Makes a simple GET request with no parameters + * Makes a simple GET request to the specified endpoint */ export async function makeSimpleGetRequest( endpoint: string, ): Promise { - const url = new URL(endpoint, baseApiUrl()); - const response = await makeAuthenticatedRequest(url.toString()); + const url = buildUrl(endpoint); + const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } /** - * Makes a GET request with pagination and filtering parameters + * Makes a paginated GET request with query parameters */ export async function makePaginatedGetRequest( endpoint: string, - params: Record, + params: Record = {}, ): Promise { const url = buildUrl(endpoint, params); const response = await makeAuthenticatedRequest(url); @@ -228,3 +283,53 @@ export async function makeGetByIdRequest( const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } + +/** + * Makes a request that can either list resources or get a single resource by ID + */ +export async function makeConsolidatedRequest( + endpoint: string, + params: Record, + idParamName: string, +): Promise { + const id = params[idParamName]; + + if (id) { + // Single resource request + return makeGetByIdRequest(endpoint, String(id)); + } else { + // List request - remove the ID param from the parameters + // eslint-disable-next-line @typescript-eslint/no-unused-vars + const { [idParamName]: _removedId, ...listParams } = params; + return makePaginatedGetRequest(endpoint, listParams); + } +} + +/** + * Makes a Trust Center request that can either list resources or get a single resource by ID + */ +export async function makeTrustCenterConsolidatedRequest( + baseEndpoint: string, + params: Record, + idParamName: string, + resourcePath: string, +): Promise { + const { slugId, [idParamName]: resourceId, ...otherParams } = params; + + if (resourceId) { + // Single resource request: /v1/trust-centers/{slugId}/{resourcePath}/{resourceId} + const url = buildUrl( + `${baseEndpoint}/${String(slugId)}/${resourcePath}/${String(resourceId)}`, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); + } else { + // List request: /v1/trust-centers/{slugId}/{resourcePath} + const url = buildUrl( + `${baseEndpoint}/${String(slugId)}/${resourcePath}`, + otherParams, + ); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); + } +} diff --git a/src/operations/controls.ts b/src/operations/controls.ts index acaec50..f0a6b9f 100644 --- a/src/operations/controls.ts +++ b/src/operations/controls.ts @@ -3,11 +3,9 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, + createConsolidatedSchema, createIdWithPaginationSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -15,51 +13,56 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const ListControlsInput = createPaginationSchema().extend({ - frameworkMatchesAny: z - .array(z.string()) - .describe( - "Filter controls by framework IDs. Returns controls that belong to any of the specified frameworks, e.g. ['soc2', 'iso27001', 'hipaa']", - ) - .optional(), -}); +const ControlsInput = createConsolidatedSchema( + { + paramName: "controlId", + description: CONTROL_ID_DESCRIPTION, + resourceName: "control", + }, + { + frameworkMatchesAny: z + .array(z.string()) + .describe( + "Filter controls by framework IDs. Returns controls that belong to any of the specified frameworks, e.g. ['soc2', 'iso27001', 'hipaa']", + ) + .optional(), + }, +); const ListControlTestsInput = createIdWithPaginationSchema({ paramName: "controlId", description: CONTROL_ID_DESCRIPTION, }); -const ListLibraryControlsInput = createPaginationSchema(); - -const ListControlDocumentsInput = createIdWithPaginationSchema({ +const ListLibraryControlsInput = createIdWithPaginationSchema({ paramName: "controlId", description: CONTROL_ID_DESCRIPTION, }); -const GetControlInput = createIdSchema({ +const ListControlDocumentsInput = createIdWithPaginationSchema({ paramName: "controlId", description: CONTROL_ID_DESCRIPTION, }); // 3. Tool Definitions -export const ListControlsTool: Tool = { - name: "list_controls", +export const ControlsTool: Tool = { + name: "controls", description: - "List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. Optionally filter by specific frameworks using frameworkMatchesAny.", - parameters: ListControlsInput, + "Access security controls in your Vanta account. Provide controlId to get a specific control, or omit to list all controls with optional framework filtering. Returns control names, descriptions, framework mappings, and implementation status.", + parameters: ControlsInput, }; export const ListControlTestsTool: Tool = { name: "list_control_tests", description: - "List a control's tests. Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests.", + "List control tests. Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control.", parameters: ListControlTestsInput, }; export const ListLibraryControlsTool: Tool = { name: "list_library_controls", description: - "List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from list_controls which lists controls already in your account - this shows available controls you can implement.", + "List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account.", parameters: ListLibraryControlsInput, }; @@ -67,22 +70,15 @@ export const ListControlDocumentsTool: Tool = { name: "list_control_documents", description: - "List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence.", + "List a control's documents. Get all documents that are associated with or provide evidence for a specific security control.", parameters: ListControlDocumentsInput, }; -export const GetControlTool: Tool = { - name: "get_control", - description: - "Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from list_controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status.", - parameters: GetControlInput, -}; - // 4. Implementation Functions -export async function listControls( - args: z.infer, +export async function controls( + args: z.infer, ): Promise { - return makePaginatedGetRequest("/v1/controls", args); + return makeConsolidatedRequest("/v1/controls", args, "controlId"); } export async function listControlTests( @@ -97,7 +93,10 @@ export async function listControlTests( export async function listLibraryControls( args: z.infer, ): Promise { - return makePaginatedGetRequest("/v1/controls/controls-library", args); + const { controlId, ...params } = args; + const url = buildUrl(`/v1/library-controls/${String(controlId)}`, params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); } export async function listControlDocuments( @@ -109,19 +108,12 @@ export async function listControlDocuments( return handleApiResponse(response); } -export async function getControl( - args: z.infer, -): Promise { - return makeGetByIdRequest("/v1/controls", args.controlId); -} - // Registry export for automated tool registration export default { tools: [ - { tool: ListControlsTool, handler: listControls }, + { tool: ControlsTool, handler: controls }, { tool: ListControlTestsTool, handler: listControlTests }, { tool: ListLibraryControlsTool, handler: listLibraryControls }, { tool: ListControlDocumentsTool, handler: listControlDocuments }, - { tool: GetControlTool, handler: getControl }, ], }; diff --git a/src/operations/documents.ts b/src/operations/documents.ts index 3cb91d7..b50e39d 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -3,11 +3,9 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, + createConsolidatedSchema, createIdWithPaginationSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -15,11 +13,10 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const ListDocumentsInput = createPaginationSchema(); - -const GetDocumentInput = createIdSchema({ +const DocumentsInput = createConsolidatedSchema({ paramName: "documentId", description: DOCUMENT_ID_DESCRIPTION, + resourceName: "document", }); const ListDocumentControlsInput = createIdWithPaginationSchema({ @@ -38,48 +35,40 @@ const ListDocumentUploadsInput = createIdWithPaginationSchema({ }); const DownloadDocumentFileInput = z.object({ - documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), uploadedFileId: z .string() .describe( - "Uploaded file ID to download, e.g. 'file-456' or specific uploaded file identifier", + "Uploaded file ID to download, e.g. 'upload-123' or specific uploaded file identifier", ), }); // 3. Tool Definitions -export const ListDocumentsTool: Tool = { - name: "list_documents", - description: - "List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls.", - parameters: ListDocumentsInput, -}; - -export const GetDocumentTool: Tool = { - name: "get_document", +export const DocumentsTool: Tool = { + name: "documents", description: - "Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from get_documents response. Returns complete document details including name, type, metadata, and compliance mappings.", - parameters: GetDocumentInput, + "Access documents in your Vanta account. Provide documentId to get a specific document, or omit to list all documents. Returns document IDs, names, types, and metadata for compliance and evidence management.", + parameters: DocumentsInput, }; export const ListDocumentControlsTool: Tool = { name: "list_document_controls", description: - "List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence.", + "List document's controls. Get all security controls that are mapped to or associated with a specific document.", parameters: ListDocumentControlsInput, }; export const ListDocumentLinksTool: Tool = { name: "list_document_links", description: - "List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence.", + "List document's links. Get all external links and references associated with a specific document.", parameters: ListDocumentLinksInput, }; export const ListDocumentUploadsTool: Tool = { name: "list_document_uploads", description: - "List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation.", + "List document's uploads. Get all files and uploads attached to a specific document for compliance documentation.", parameters: ListDocumentUploadsInput, }; @@ -87,21 +76,15 @@ export const DownloadDocumentFileTool: Tool = { name: "download_document_file", description: - "Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed.", + "Download document file by upload ID. Get the actual uploaded document file. Intelligently handles different MIME types: returns text content for readable files (text/*, JSON, XML, CSV, JavaScript) and metadata information for binary files (images, videos, PDFs, etc.).", parameters: DownloadDocumentFileInput, }; // 4. Implementation Functions -export async function listDocuments( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/documents", args); -} - -export async function getDocument( - args: z.infer, +export async function documents( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/documents", args.documentId); + return makeConsolidatedRequest("/v1/documents", args, "documentId"); } export async function listDocumentControls( @@ -135,7 +118,7 @@ export async function downloadDocumentFile( args: z.infer, ): Promise { const url = buildUrl( - `/v1/documents/${String(args.documentId)}/uploads/${String(args.uploadedFileId)}/media`, + `/v1/document-uploads/${String(args.uploadedFileId)}/download`, ); const response = await makeAuthenticatedRequest(url); @@ -163,7 +146,7 @@ export async function downloadDocumentFile( content: [ { type: "text" as const, - text: `File Content (${contentType}):\n\n${textContent}`, + text: `Document File Content (${contentType}):\n\n${textContent}`, }, ], }; @@ -172,25 +155,26 @@ export async function downloadDocumentFile( content: [ { type: "text" as const, - text: `Error reading text content: ${String(error)}`, + text: `Error reading text content: ${error instanceof Error ? error.message : "Unknown error"}`, }, ], + isError: true, }; } } - // For binary files, return metadata instead of raw binary data + // For binary files, return metadata about the file return { content: [ { type: "text" as const, - text: `Binary File Information: -MIME Type: ${contentType} -Content Length: ${contentLength ? `${contentLength} bytes` : "Unknown"} -Document ID: ${args.documentId} -Uploaded File ID: ${args.uploadedFileId} + text: `Document File Information: +- Content Type: ${contentType} +- Content Length: ${contentLength ? `${contentLength} bytes` : "Unknown"} +- File Type: ${contentType.startsWith("image/") ? "Image" : contentType.startsWith("video/") ? "Video" : contentType.startsWith("audio/") ? "Audio" : contentType.startsWith("application/pdf") ? "PDF Document" : "Binary File"} +- Upload ID: ${String(args.uploadedFileId)} -Note: This is a binary file (${contentType.split("/")[0]} format) that cannot be displayed as text. Use get_document_uploads to see file metadata, or access the file directly through the Vanta web interface for viewing.`, +Note: This is a binary file. Use appropriate tools to download and process the actual file content.`, }, ], }; @@ -199,8 +183,7 @@ Note: This is a binary file (${contentType.split("/")[0]} format) that cannot be // Registry export for automated tool registration export default { tools: [ - { tool: ListDocumentsTool, handler: listDocuments }, - { tool: GetDocumentTool, handler: getDocument }, + { tool: DocumentsTool, handler: documents }, { tool: ListDocumentControlsTool, handler: listDocumentControls }, { tool: ListDocumentLinksTool, handler: listDocumentLinks }, { tool: ListDocumentUploadsTool, handler: listDocumentUploads }, diff --git a/src/operations/frameworks.ts b/src/operations/frameworks.ts index b0310f2..79675b0 100644 --- a/src/operations/frameworks.ts +++ b/src/operations/frameworks.ts @@ -3,11 +3,9 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, + createConsolidatedSchema, createIdWithPaginationSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -15,24 +13,23 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const ListFrameworksInput = createPaginationSchema(); - -const ListFrameworkControlsInput = createIdWithPaginationSchema({ +const FrameworksInput = createConsolidatedSchema({ paramName: "frameworkId", description: FRAMEWORK_ID_DESCRIPTION, + resourceName: "framework", }); -const GetFrameworkInput = createIdSchema({ +const ListFrameworkControlsInput = createIdWithPaginationSchema({ paramName: "frameworkId", description: FRAMEWORK_ID_DESCRIPTION, }); // 3. Tool Definitions -export const ListFrameworksTool: Tool = { - name: "list_frameworks", +export const FrameworksTool: Tool = { + name: "frameworks", description: - "List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state including status of controls, documents, and tests for each framework.", - parameters: ListFrameworksInput, + "Access compliance frameworks in your Vanta account. Provide frameworkId to get a specific framework, or omit to list all frameworks. Returns frameworks (SOC 2, ISO 27001, HIPAA, GDPR, etc.) with completion status and progress metrics.", + parameters: FrameworksInput, }; export const ListFrameworkControlsTool: Tool< @@ -40,18 +37,17 @@ export const ListFrameworkControlsTool: Tool< > = { name: "list_framework_controls", description: - "Get the detailed CONTROL REQUIREMENTS for a specific framework (requires frameworkId). Use this when you need the specific control details, requirements, and implementation guidance for a known framework like 'soc2' or 'iso27001'. This returns the actual security controls and their descriptions, NOT the framework list. Use list_frameworks first if you need to see available frameworks.", + "List framework's controls. Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status.", parameters: ListFrameworkControlsInput, }; -export const GetFrameworkTool: Tool = { - name: "get_framework", - description: - "Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from list_frameworks response. Returns complete framework details including description, requirements, completion status, and associated controls.", - parameters: GetFrameworkInput, -}; - // 4. Implementation Functions +export async function frameworks( + args: z.infer, +): Promise { + return makeConsolidatedRequest("/v1/frameworks", args, "frameworkId"); +} + export async function listFrameworkControls( args: z.infer, ): Promise { @@ -64,23 +60,10 @@ export async function listFrameworkControls( return handleApiResponse(response); } -export async function listFrameworks( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/frameworks", args); -} - -export async function getFramework( - args: z.infer, -): Promise { - return makeGetByIdRequest("/v1/frameworks", args.frameworkId); -} - // Registry export for automated tool registration export default { tools: [ - { tool: ListFrameworksTool, handler: listFrameworks }, + { tool: FrameworksTool, handler: frameworks }, { tool: ListFrameworkControlsTool, handler: listFrameworkControls }, - { tool: GetFrameworkTool, handler: getFramework }, ], }; diff --git a/src/operations/groups.ts b/src/operations/groups.ts index 2433b32..ab3a8d8 100644 --- a/src/operations/groups.ts +++ b/src/operations/groups.ts @@ -3,23 +3,20 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, + createConsolidatedSchema, createIdWithPaginationSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, } from "./common/imports.js"; // 2. Input Schemas -const ListGroupsInput = createPaginationSchema(); - -const GetGroupInput = createIdSchema({ +const GroupsInput = createConsolidatedSchema({ paramName: "groupId", description: "Group ID to retrieve, e.g. 'group-123' or specific group identifier", + resourceName: "group", }); const ListGroupPeopleInput = createIdWithPaginationSchema({ @@ -29,38 +26,25 @@ const ListGroupPeopleInput = createIdWithPaginationSchema({ }); // 3. Tool Definitions -export const ListGroupsTool: Tool = { - name: "list_groups", - description: - "List all groups in your Vanta account. Returns group IDs, names, descriptions, and member counts for organizational structure management. Use this to see all available groups for access control and compliance.", - parameters: ListGroupsInput, -}; - -export const GetGroupTool: Tool = { - name: "get_group", +export const GroupsTool: Tool = { + name: "groups", description: - "Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from list_groups response. Returns complete group details including name, description, member list, and access permissions.", - parameters: GetGroupInput, + "Access groups in your Vanta account. Provide groupId to get a specific group, or omit to list all groups. Returns group IDs, names, descriptions, and metadata for organizational structure and access management.", + parameters: GroupsInput, }; export const ListGroupPeopleTool: Tool = { name: "list_group_people", description: - "List people in a group. Get all people who are members of a specific group for access management and organizational oversight. Returns person details including names, emails, and roles within the group.", + "List group's people. Get all people who are members of a specific group. Use this to see group membership and organizational structure.", parameters: ListGroupPeopleInput, }; // 4. Implementation Functions -export async function listGroups( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/groups", args); -} - -export async function getGroup( - args: z.infer, +export async function groups( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/groups", args.groupId); + return makeConsolidatedRequest("/v1/groups", args, "groupId"); } export async function listGroupPeople( @@ -75,8 +59,7 @@ export async function listGroupPeople( // Registry export for automated tool registration export default { tools: [ - { tool: ListGroupsTool, handler: listGroups }, - { tool: GetGroupTool, handler: getGroup }, + { tool: GroupsTool, handler: groups }, { tool: ListGroupPeopleTool, handler: listGroupPeople }, ], }; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index 354acda..b96aabb 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -3,10 +3,9 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + createIdWithPaginationSchema, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -14,16 +13,15 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const ListIntegrationsInput = createPaginationSchema(); - -const GetIntegrationInput = createIdSchema({ +const IntegrationsInput = createConsolidatedSchema({ paramName: "integrationId", description: INTEGRATION_ID_DESCRIPTION, + resourceName: "integration", }); -const ListIntegrationResourceKindsInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - ...createPaginationSchema().shape, +const ListIntegrationResourceKindsInput = createIdWithPaginationSchema({ + paramName: "integrationId", + description: INTEGRATION_ID_DESCRIPTION, }); const GetIntegrationResourceKindDetailsInput = z.object({ @@ -31,7 +29,7 @@ const GetIntegrationResourceKindDetailsInput = z.object({ resourceKind: z .string() .describe( - "Resource kind to get details for, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + "Resource kind to get details for, e.g. 'ec2-instances' or specific resource kind identifier", ), }); @@ -40,9 +38,18 @@ const ListIntegrationResourcesInput = z.object({ resourceKind: z .string() .describe( - "Resource kind to list resources for, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + "Resource kind to list resources for, e.g. 'ec2-instances' or specific resource kind identifier", ), - ...createPaginationSchema().shape, + pageSize: z + .number() + .min(1) + .max(100) + .describe("Number of items to return per page (1-100)") + .optional(), + pageCursor: z + .string() + .describe("Cursor for pagination to get the next page of results") + .optional(), }); const GetIntegrationResourceInput = z.object({ @@ -50,28 +57,21 @@ const GetIntegrationResourceInput = z.object({ resourceKind: z .string() .describe( - "Resource kind to get resource from, e.g. 'S3Bucket', 'CloudwatchLogGroup'", + "Resource kind the resource belongs to, e.g. 'ec2-instances' or specific resource kind identifier", ), resourceId: z .string() .describe( - "Resource ID to get details for, e.g. 'i-1234567890abcdef0', 'bucket-name'", + "Resource ID to retrieve, e.g. 'resource-123' or specific resource identifier", ), }); // 3. Tool Definitions -export const ListIntegrationsTool: Tool = { - name: "list_integrations", +export const IntegrationsTool: Tool = { + name: "integrations", description: - "List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance.", - parameters: ListIntegrationsInput, -}; - -export const GetIntegrationTool: Tool = { - name: "get_integration", - description: - "Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from get_integrations response. Returns complete integration details including configuration, resource kinds, and connection status.", - parameters: GetIntegrationInput, + "Access connected integrations in your Vanta account. Provide integrationId to get a specific integration, or omit to list all integrations. Returns integration details, supported resource kinds, and connection status for compliance monitoring.", + parameters: IntegrationsInput, }; export const ListIntegrationResourceKindsTool: Tool< @@ -79,7 +79,7 @@ export const ListIntegrationResourceKindsTool: Tool< > = { name: "list_integration_resource_kinds", description: - "List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor.", + "List integration's resource kinds. Get all resource types that are available through a specific integration. Use this to see what kinds of resources (EC2 instances, S3 buckets, etc.) can be monitored through an integration.", parameters: ListIntegrationResourceKindsInput, }; @@ -88,7 +88,7 @@ export const GetIntegrationResourceKindDetailsTool: Tool< > = { name: "get_integration_resource_kind_details", description: - "Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type.", + "Get integration resource kind details. Get detailed information about a specific resource kind within an integration. Use this to understand the schema and available fields for a particular resource type.", parameters: GetIntegrationResourceKindDetailsInput, }; @@ -97,7 +97,7 @@ export const ListIntegrationResourcesTool: Tool< > = { name: "list_integration_resources", description: - "List resources for a specific resource kind. List all resources of a specific type (kind) discovered by an integration. Use this to see all infrastructure resources of a particular type that Vanta is monitoring through an integration.", + "List integration resources. Get all resources of a specific type within an integration. Use this to see all instances of a particular resource kind (like all EC2 instances) being monitored through an integration.", parameters: ListIntegrationResourcesInput, }; @@ -106,21 +106,15 @@ export const GetIntegrationResourceTool: Tool< > = { name: "get_integration_resource", description: - "Get resource by ID within a specific resource kind. Retrieve detailed information about a specific resource of a particular type discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration.", + "Get integration resource by ID. Get detailed information about a specific resource within an integration. Use this to see the current state and attributes of a particular monitored resource.", parameters: GetIntegrationResourceInput, }; // 4. Implementation Functions -export async function listIntegrations( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/integrations", args); -} - -export async function getIntegration( - args: z.infer, +export async function integrations( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/integrations", args.integrationId); + return makeConsolidatedRequest("/v1/integrations", args, "integrationId"); } export async function listIntegrationResourceKinds( @@ -170,8 +164,7 @@ export async function getIntegrationResource( // Registry export for automated tool registration export default { tools: [ - { tool: ListIntegrationsTool, handler: listIntegrations }, - { tool: GetIntegrationTool, handler: getIntegration }, + { tool: IntegrationsTool, handler: integrations }, { tool: ListIntegrationResourceKindsTool, handler: listIntegrationResourceKinds, diff --git a/src/operations/monitored-computers.ts b/src/operations/monitored-computers.ts index e2b50af..76e6eb3 100644 --- a/src/operations/monitored-computers.ts +++ b/src/operations/monitored-computers.ts @@ -3,56 +3,38 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + makeConsolidatedRequest, } from "./common/imports.js"; // 2. Input Schemas -const ListMonitoredComputersInput = createPaginationSchema(); - -const GetMonitoredComputerInput = createIdSchema({ - paramName: "computerId", +const MonitoredComputersInput = createConsolidatedSchema({ + paramName: "monitoredComputerId", description: - "Computer ID to retrieve, e.g. 'computer-123' or specific computer identifier", + "Monitored computer ID to retrieve, e.g. 'comp-123' or specific monitored computer identifier", + resourceName: "monitored computer", }); // 3. Tool Definitions -export const ListMonitoredComputersTool: Tool< - typeof ListMonitoredComputersInput -> = { - name: "list_monitored_computers", +export const MonitoredComputersTool: Tool = { + name: "monitored_computers", description: - "List all monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and monitoring status for endpoint management. Use this to see all computers being monitored for compliance and security.", - parameters: ListMonitoredComputersInput, + "Access monitored computers in your Vanta account. Provide monitoredComputerId to get a specific computer, or omit to list all monitored computers. Returns computer details, compliance status, and security measures for device management.", + parameters: MonitoredComputersInput, }; -export const GetMonitoredComputerTool: Tool = - { - name: "get_monitored_computer", - description: - "Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from list_monitored_computers response. Returns complete computer details including hardware specs, software inventory, and compliance status.", - parameters: GetMonitoredComputerInput, - }; - // 4. Implementation Functions -export async function listMonitoredComputers( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/monitored-computers", args); -} - -export async function getMonitoredComputer( - args: z.infer, +export async function monitoredComputers( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/monitored-computers", args.computerId); + return makeConsolidatedRequest( + "/v1/monitored-computers", + args, + "monitoredComputerId", + ); } // Registry export for automated tool registration export default { - tools: [ - { tool: ListMonitoredComputersTool, handler: listMonitoredComputers }, - { tool: GetMonitoredComputerTool, handler: getMonitoredComputer }, - ], + tools: [{ tool: MonitoredComputersTool, handler: monitoredComputers }], }; diff --git a/src/operations/people.ts b/src/operations/people.ts index 1cf81e4..221412d 100644 --- a/src/operations/people.ts +++ b/src/operations/people.ts @@ -3,53 +3,34 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + makeConsolidatedRequest, } from "./common/imports.js"; // 2. Input Schemas -const ListPeopleInput = createPaginationSchema(); - -const GetPersonInput = createIdSchema({ +const PeopleInput = createConsolidatedSchema({ paramName: "personId", description: "Person ID to retrieve, e.g. 'person-123' or specific person identifier", + resourceName: "person", }); // 3. Tool Definitions -export const ListPeopleTool: Tool = { - name: "list_people", - description: - "List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management.", - parameters: ListPeopleInput, -}; - -export const GetPersonTool: Tool = { - name: "get_person", +export const PeopleTool: Tool = { + name: "people", description: - "Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from get_people response. Returns complete person details including name, email, role, group memberships, and access permissions.", - parameters: GetPersonInput, + "Access people in your Vanta account. Provide personId to get a specific person, or omit to list all people. Returns person IDs, names, email addresses, and organizational information for identity and access management.", + parameters: PeopleInput, }; // 4. Implementation Functions -export async function listPeople( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/people", args); -} - -export async function getPerson( - args: z.infer, +export async function people( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/people", args.personId); + return makeConsolidatedRequest("/v1/people", args, "personId"); } // Registry export for automated tool registration export default { - tools: [ - { tool: ListPeopleTool, handler: listPeople }, - { tool: GetPersonTool, handler: getPerson }, - ], + tools: [{ tool: PeopleTool, handler: people }], }; diff --git a/src/operations/policies.ts b/src/operations/policies.ts index 09f9b2e..cc0dd81 100644 --- a/src/operations/policies.ts +++ b/src/operations/policies.ts @@ -3,53 +3,34 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + makeConsolidatedRequest, } from "./common/imports.js"; // 2. Input Schemas -const ListPoliciesInput = createPaginationSchema(); - -const GetPolicyInput = createIdSchema({ +const PoliciesInput = createConsolidatedSchema({ paramName: "policyId", description: "Policy ID to retrieve, e.g. 'policy-123' or specific policy identifier", + resourceName: "policy", }); // 3. Tool Definitions -export const ListPoliciesTool: Tool = { - name: "list_policies", - description: - "List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance.", - parameters: ListPoliciesInput, -}; - -export const GetPolicyTool: Tool = { - name: "get_policy", +export const PoliciesTool: Tool = { + name: "policies", description: - "Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from get_policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings.", - parameters: GetPolicyInput, + "Access policies in your Vanta account. Provide policyId to get a specific policy, or omit to list all policies. Returns policy IDs, names, and metadata for governance and compliance management.", + parameters: PoliciesInput, }; // 4. Implementation Functions -export async function listPolicies( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/policies", args); -} - -export async function getPolicy( - args: z.infer, +export async function policies( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/policies", args.policyId); + return makeConsolidatedRequest("/v1/policies", args, "policyId"); } // Registry export for automated tool registration export default { - tools: [ - { tool: ListPoliciesTool, handler: listPolicies }, - { tool: GetPolicyTool, handler: getPolicy }, - ], + tools: [{ tool: PoliciesTool, handler: policies }], }; diff --git a/src/operations/risks.ts b/src/operations/risks.ts index 1fc43a9..956dbd2 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -3,59 +3,44 @@ import { CallToolResult, Tool, z, - createFilterSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + makeConsolidatedRequest, } from "./common/imports.js"; // 2. Input Schemas -const ListRisksInput = createFilterSchema({ - categoryMatchesAny: z - .string() - .optional() - .describe( - "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc.", - ), -}); - -const GetRiskInput = createIdSchema({ - paramName: "riskId", - description: - "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier", -}); +const RisksInput = createConsolidatedSchema( + { + paramName: "riskId", + description: + "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier", + resourceName: "risk scenario", + }, + { + categoryMatchesAny: z + .string() + .optional() + .describe( + "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc.", + ), + }, +); // 3. Tool Definitions -export const ListRisksTool: Tool = { - name: "list_risks", - description: "List all risk scenarios in your Vanta risk register.", - parameters: ListRisksInput, -}; - -export const GetRiskTool: Tool = { - name: "get_risk", +export const RisksTool: Tool = { + name: "risks", description: - "Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from list_risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more.", - parameters: GetRiskInput, + "Access risk scenarios in your Vanta account. Provide riskId to get a specific risk scenario, or omit to list all risks with optional category filtering. Returns risk details, assessments, and mitigation strategies for compliance reporting.", + parameters: RisksInput, }; // 4. Implementation Functions -export async function listRisks( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/risk-scenarios", args); -} - -export async function getRisk( - args: z.infer, +export async function risks( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/risk-scenarios", args.riskId); + return makeConsolidatedRequest("/v1/risk-scenarios", args, "riskId"); } // Registry export for automated tool registration export default { - tools: [ - { tool: ListRisksTool, handler: listRisks }, - { tool: GetRiskTool, handler: getRisk }, - ], + tools: [{ tool: RisksTool, handler: risks }], }; diff --git a/src/operations/tests.ts b/src/operations/tests.ts index dd18f05..ae60a21 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -3,32 +3,36 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, + createConsolidatedSchema, createIdWithPaginationSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, } from "./common/imports.js"; // 2. Input Schemas -const ListTestEntitiesInput = createIdWithPaginationSchema({ +const TestsInput = createConsolidatedSchema({ paramName: "testId", description: - "Test ID to get entities for, e.g. 'test-123' or specific test identifier", + "Test ID to retrieve, e.g. 'test-123' or specific test identifier", + resourceName: "test", }); -const ListTestsInput = createPaginationSchema(); - -const GetTestInput = createIdSchema({ +const ListTestEntitiesInput = createIdWithPaginationSchema({ paramName: "testId", description: - "Test ID to retrieve, e.g. 'test-123' or specific test identifier", + "Test ID to get entities for, e.g. 'test-123' or specific test identifier", }); // 3. Tool Definitions +export const TestsTool: Tool = { + name: "tests", + description: + "Access security tests in your Vanta account. Provide testId to get a specific test, or omit to list all tests. Returns test IDs, names, types, schedules, current status, and detailed configuration for compliance monitoring.", + parameters: TestsInput, +}; + export const ListTestEntitiesTool: Tool = { name: "list_test_entities", description: @@ -36,21 +40,13 @@ export const ListTestEntitiesTool: Tool = { parameters: ListTestEntitiesInput, }; -export const ListTestsTool: Tool = { - name: "list_tests", - description: - "List all security tests configured in your Vanta account. Returns test IDs, names, types, schedules, and current status for compliance monitoring. Use this to see all automated and manual tests running for your security controls.", - parameters: ListTestsInput, -}; - -export const GetTestTool: Tool = { - name: "get_test", - description: - "Get test by ID. Retrieve detailed information about a specific security test when its ID is known. The ID of a test can be found from list_tests response. Returns complete test details including configuration, execution history, results, and associated controls.", - parameters: GetTestInput, -}; - // 4. Implementation Functions +export async function tests( + args: z.infer, +): Promise { + return makeConsolidatedRequest("/v1/tests", args, "testId"); +} + export async function listTestEntities( args: z.infer, ): Promise { @@ -60,23 +56,10 @@ export async function listTestEntities( return handleApiResponse(response); } -export async function listTests( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/tests", args); -} - -export async function getTest( - args: z.infer, -): Promise { - return makeGetByIdRequest("/v1/tests", args.testId); -} - // Registry export for automated tool registration export default { tools: [ - { tool: ListTestsTool, handler: listTests }, + { tool: TestsTool, handler: tests }, { tool: ListTestEntitiesTool, handler: listTestEntities }, - { tool: GetTestTool, handler: getTest }, ], }; diff --git a/src/operations/trust-centers.ts b/src/operations/trust-centers.ts index 2a6e48a..ac4d851 100644 --- a/src/operations/trust-centers.ts +++ b/src/operations/trust-centers.ts @@ -5,7 +5,9 @@ import { z, createIdSchema, createIdWithPaginationSchema, + createTrustCenterConsolidatedSchema, makeGetByIdRequest, + makeTrustCenterConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -18,18 +20,11 @@ const GetTrustCenterInput = createIdSchema({ description: SLUG_ID_DESCRIPTION, }); -const ListTrustCenterAccessRequestsInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, -}); - -const GetTrustCenterAccessRequestInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - accessRequestId: z - .string() - .describe( - "Access request ID to retrieve, e.g. 'request-123' or specific access request identifier", - ), +const TrustCenterAccessRequestsInput = createTrustCenterConsolidatedSchema({ + paramName: "accessRequestId", + description: + "Access request ID to retrieve, e.g. 'request-123' or specific access request identifier", + resourceName: "access request", }); const ListTrustCenterViewerActivityEventsInput = createIdWithPaginationSchema({ @@ -37,44 +32,24 @@ const ListTrustCenterViewerActivityEventsInput = createIdWithPaginationSchema({ description: SLUG_ID_DESCRIPTION, }); -const ListTrustCenterControlCategoriesInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, -}); - -const GetTrustCenterControlCategoryInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - controlCategoryId: z - .string() - .describe( - "Control category ID to retrieve, e.g. 'category-123' or specific control category identifier", - ), -}); - -const ListTrustCenterControlsInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, -}); - -const GetTrustCenterControlInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - trustCenterControlId: z - .string() - .describe( - "Trust Center control ID to retrieve, e.g. 'tc-control-123' or specific Trust Center control identifier", - ), +const TrustCenterControlCategoriesInput = createTrustCenterConsolidatedSchema({ + paramName: "controlCategoryId", + description: + "Control category ID to retrieve, e.g. 'category-123' or specific control category identifier", + resourceName: "control category", }); -const ListTrustCenterFaqsInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, +const TrustCenterControlsInput = createTrustCenterConsolidatedSchema({ + paramName: "trustCenterControlId", + description: + "Trust Center control ID to retrieve, e.g. 'tc-control-123' or specific Trust Center control identifier", + resourceName: "control", }); -const GetTrustCenterFaqInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - faqId: z - .string() - .describe("FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier"), +const TrustCenterFaqsInput = createTrustCenterConsolidatedSchema({ + paramName: "faqId", + description: "FAQ ID to retrieve, e.g. 'faq-123' or specific FAQ identifier", + resourceName: "FAQ", }); const ListTrustCenterResourcesInput = createIdWithPaginationSchema({ @@ -100,46 +75,25 @@ const GetTrustCenterResourceMediaInput = z.object({ ), }); -const ListTrustCenterSubprocessorsInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, -}); - -const GetTrustCenterSubprocessorInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - subprocessorId: z - .string() - .describe( - "Subprocessor ID to retrieve, e.g. 'subprocessor-123' or specific subprocessor identifier", - ), -}); - -const ListTrustCenterUpdatesInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, -}); - -const GetTrustCenterUpdateInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - updateId: z - .string() - .describe( - "Update ID to retrieve, e.g. 'update-123' or specific update identifier", - ), +const TrustCenterSubprocessorsInput = createTrustCenterConsolidatedSchema({ + paramName: "subprocessorId", + description: + "Subprocessor ID to retrieve, e.g. 'subprocessor-123' or specific subprocessor identifier", + resourceName: "subprocessor", }); -const ListTrustCenterViewersInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, +const TrustCenterUpdatesInput = createTrustCenterConsolidatedSchema({ + paramName: "updateId", + description: + "Update ID to retrieve, e.g. 'update-123' or specific update identifier", + resourceName: "update", }); -const GetTrustCenterViewerInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - viewerId: z - .string() - .describe( - "Viewer ID to retrieve, e.g. 'viewer-123' or specific viewer identifier", - ), +const TrustCenterViewersInput = createTrustCenterConsolidatedSchema({ + paramName: "viewerId", + description: + "Viewer ID to retrieve, e.g. 'viewer-123' or specific viewer identifier", + resourceName: "viewer", }); const GetTrustCenterSubscriberInput = z.object({ @@ -151,18 +105,11 @@ const GetTrustCenterSubscriberInput = z.object({ ), }); -const GetTrustCenterSubscriberGroupInput = z.object({ - slugId: z.string().describe(SLUG_ID_DESCRIPTION), - subscriberGroupId: z - .string() - .describe( - "Subscriber group ID to retrieve, e.g. 'group-123' or specific subscriber group identifier", - ), -}); - -const ListTrustCenterSubscriberGroupsInput = createIdWithPaginationSchema({ - paramName: "slugId", - description: SLUG_ID_DESCRIPTION, +const TrustCenterSubscriberGroupsInput = createTrustCenterConsolidatedSchema({ + paramName: "subscriberGroupId", + description: + "Subscriber group ID to retrieve, e.g. 'group-123' or specific subscriber group identifier", + resourceName: "subscriber group", }); const ListTrustCenterHistoricalAccessRequestsInput = @@ -184,22 +131,13 @@ export const GetTrustCenterTool: Tool = { parameters: GetTrustCenterInput, }; -export const ListTrustCenterAccessRequestsTool: Tool< - typeof ListTrustCenterAccessRequestsInput -> = { - name: "list_trust_center_access_requests", - description: - "List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information.", - parameters: ListTrustCenterAccessRequestsInput, -}; - -export const GetTrustCenterAccessRequestTool: Tool< - typeof GetTrustCenterAccessRequestInput +export const TrustCenterAccessRequestsTool: Tool< + typeof TrustCenterAccessRequestsInput > = { - name: "get_trust_center_access_request", + name: "trust_center_access_requests", description: - "Get Trust Center access request by ID. Retrieve detailed information about a specific access request to a Trust Center. Use this to review individual access requests including requester details, status, and approval workflow.", - parameters: GetTrustCenterAccessRequestInput, + "Access Trust Center access requests. Provide accessRequestId to get a specific access request, or omit to list all access requests. Use this to manage and review Trust Center access requests including requester details, status, and approval workflow.", + parameters: TrustCenterAccessRequestsInput, }; export const ListTrustCenterViewerActivityEventsTool: Tool< @@ -211,54 +149,27 @@ export const ListTrustCenterViewerActivityEventsTool: Tool< parameters: ListTrustCenterViewerActivityEventsInput, }; -export const ListTrustCenterControlCategoriesTool: Tool< - typeof ListTrustCenterControlCategoriesInput +export const TrustCenterControlCategoriesTool: Tool< + typeof TrustCenterControlCategoriesInput > = { - name: "list_trust_center_control_categories", + name: "trust_center_control_categories", description: - "List Trust Center control categories. Get all available control categories displayed in a specific Trust Center. Use this to understand how compliance controls are organized and presented to your customers.", - parameters: ListTrustCenterControlCategoriesInput, + "Access Trust Center control categories. Provide controlCategoryId to get a specific control category, or omit to list all categories. Use this to understand how compliance controls are organized and categorized for public display.", + parameters: TrustCenterControlCategoriesInput, }; -export const GetTrustCenterControlCategoryTool: Tool< - typeof GetTrustCenterControlCategoryInput -> = { - name: "get_trust_center_control_category", +export const TrustCenterControlsTool: Tool = { + name: "trust_center_controls", description: - "Get Trust Center control category by ID. Retrieve detailed information about a specific control category in a Trust Center. Use this to get category details, descriptions, and associated controls.", - parameters: GetTrustCenterControlCategoryInput, + "Access Trust Center controls. Provide trustCenterControlId to get a specific control, or omit to list all controls. Use this to see compliance controls displayed publicly to demonstrate your compliance posture.", + parameters: TrustCenterControlsInput, }; -export const ListTrustCenterControlsTool: Tool< - typeof ListTrustCenterControlsInput -> = { - name: "list_trust_center_controls", - description: - "List Trust Center controls. Get all compliance controls visible in a specific Trust Center. Use this to see what security controls are publicly displayed to demonstrate your compliance posture.", - parameters: ListTrustCenterControlsInput, -}; - -export const GetTrustCenterControlTool: Tool< - typeof GetTrustCenterControlInput -> = { - name: "get_trust_center_control", - description: - "Get Trust Center control by ID. Retrieve detailed information about a specific control displayed in a Trust Center. Use this to get control implementation details, evidence, and public-facing descriptions.", - parameters: GetTrustCenterControlInput, -}; - -export const ListTrustCenterFaqsTool: Tool = { - name: "list_trust_center_faqs", - description: - "List Trust Center FAQs. Get all frequently asked questions published in a specific Trust Center. Use this to review customer-facing compliance and security information.", - parameters: ListTrustCenterFaqsInput, -}; - -export const GetTrustCenterFaqTool: Tool = { - name: "get_trust_center_faq", +export const TrustCenterFaqsTool: Tool = { + name: "trust_center_faqs", description: - "Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ item in a Trust Center. Use this to get the full question, answer, and any supporting documentation.", - parameters: GetTrustCenterFaqInput, + "Access Trust Center FAQs. Provide faqId to get a specific FAQ, or omit to list all FAQs. Use this to see frequently asked questions and answers published for customers regarding compliance and security practices.", + parameters: TrustCenterFaqsInput, }; export const ListTrustCenterResourcesTool: Tool< @@ -288,58 +199,29 @@ export const GetTrustCenterResourceMediaTool: Tool< parameters: GetTrustCenterResourceMediaInput, }; -export const ListTrustCenterSubprocessorsTool: Tool< - typeof ListTrustCenterSubprocessorsInput -> = { - name: "list_trust_center_subprocessors", - description: - "List Trust Center subprocessors. Get all subprocessors displayed in a specific Trust Center. Use this to see third-party service providers and their compliance information for transparency.", - parameters: ListTrustCenterSubprocessorsInput, -}; - -export const GetTrustCenterSubprocessorTool: Tool< - typeof GetTrustCenterSubprocessorInput +export const TrustCenterSubprocessorsTool: Tool< + typeof TrustCenterSubprocessorsInput > = { - name: "get_trust_center_subprocessor", + name: "trust_center_subprocessors", description: - "Get Trust Center subprocessor by ID. Retrieve detailed information about a specific subprocessor including compliance details, certifications, and data processing information.", - parameters: GetTrustCenterSubprocessorInput, + "Access Trust Center subprocessors. Provide subprocessorId to get a specific subprocessor, or omit to list all subprocessors. Use this to see third-party service providers and their compliance information for transparency.", + parameters: TrustCenterSubprocessorsInput, }; -export const ListTrustCenterUpdatesTool: Tool< - typeof ListTrustCenterUpdatesInput -> = { - name: "list_trust_center_updates", +export const TrustCenterUpdatesTool: Tool = { + name: "trust_center_updates", description: - "List Trust Center updates. Get all updates and announcements published in a specific Trust Center. Use this to see compliance status changes, security updates, and important notifications.", - parameters: ListTrustCenterUpdatesInput, + "Access Trust Center updates. Provide updateId to get a specific update, or omit to list all updates. Use this to see compliance status changes, security updates, and important notifications published in the Trust Center.", + parameters: TrustCenterUpdatesInput, }; -export const GetTrustCenterUpdateTool: Tool = - { - name: "get_trust_center_update", - description: - "Get Trust Center update by ID. Retrieve detailed information about a specific update including content, publication date, and impact on compliance status.", - parameters: GetTrustCenterUpdateInput, - }; - -export const ListTrustCenterViewersTool: Tool< - typeof ListTrustCenterViewersInput -> = { - name: "list_trust_center_viewers", +export const TrustCenterViewersTool: Tool = { + name: "trust_center_viewers", description: - "List Trust Center viewers. Get all users who have access to view a specific Trust Center. Use this for access management and audit purposes.", - parameters: ListTrustCenterViewersInput, + "Access Trust Center viewers. Provide viewerId to get a specific viewer, or omit to list all viewers. Use this for access management and audit purposes to see who can view the Trust Center.", + parameters: TrustCenterViewersInput, }; -export const GetTrustCenterViewerTool: Tool = - { - name: "get_trust_center_viewer", - description: - "Get Trust Center viewer by ID. Retrieve detailed information about a specific viewer including access permissions, activity history, and contact information.", - parameters: GetTrustCenterViewerInput, - }; - export const GetTrustCenterSubscriberTool: Tool< typeof GetTrustCenterSubscriberInput > = { @@ -349,22 +231,13 @@ export const GetTrustCenterSubscriberTool: Tool< parameters: GetTrustCenterSubscriberInput, }; -export const GetTrustCenterSubscriberGroupTool: Tool< - typeof GetTrustCenterSubscriberGroupInput +export const TrustCenterSubscriberGroupsTool: Tool< + typeof TrustCenterSubscriberGroupsInput > = { - name: "get_trust_center_subscriber_group", + name: "trust_center_subscriber_groups", description: - "Get Trust Center subscriber group by ID. Retrieve detailed information about a specific subscriber group including members and notification preferences.", - parameters: GetTrustCenterSubscriberGroupInput, -}; - -export const ListTrustCenterSubscriberGroupsTool: Tool< - typeof ListTrustCenterSubscriberGroupsInput -> = { - name: "list_trust_center_subscriber_groups", - description: - "List Trust Center subscriber groups. Get all subscriber groups configured for a specific Trust Center. Use this to manage notification groups and communication preferences.", - parameters: ListTrustCenterSubscriberGroupsInput, + "Access Trust Center subscriber groups. Provide subscriberGroupId to get a specific subscriber group, or omit to list all subscriber groups. Use this for managing access permissions and organizing subscribers.", + parameters: TrustCenterSubscriberGroupsInput, }; export const ListTrustCenterHistoricalAccessRequestsTool: Tool< @@ -372,7 +245,7 @@ export const ListTrustCenterHistoricalAccessRequestsTool: Tool< > = { name: "list_trust_center_historical_access_requests", description: - "List Trust Center historical access requests. Get all past access requests for a specific Trust Center including approved, denied, and expired requests for audit and compliance tracking.", + "List Trust Center historical access requests. Get all historical access requests for a specific Trust Center for auditing and compliance tracking. Use this to review past access patterns and requests.", parameters: ListTrustCenterHistoricalAccessRequestsInput, }; @@ -381,7 +254,7 @@ export const ListTrustCenterSubscribersTool: Tool< > = { name: "list_trust_center_subscribers", description: - "List Trust Center subscribers. Get all subscribers to a specific Trust Center for update notifications and communication management.", + "List Trust Center subscribers. Get all subscribers for a specific Trust Center. Use this to manage notifications and communication with stakeholders.", parameters: ListTrustCenterSubscribersInput, }; @@ -389,29 +262,18 @@ export const ListTrustCenterSubscribersTool: Tool< export async function getTrustCenter( args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/trust-centers", args.slugId); + return makeGetByIdRequest("/v1/trust-centers", String(args.slugId)); } -export async function listTrustCenterAccessRequests( - args: z.infer, +export async function trustCenterAccessRequests( + args: z.infer, ): Promise { - const { slugId, ...params } = args; - const url = buildUrl( - `/v1/trust-centers/${String(slugId)}/access-requests`, - params, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "accessRequestId", + "access-requests", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function getTrustCenterAccessRequest( - args: z.infer, -): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/access-requests/${String(args.accessRequestId)}`, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } export async function listTrustCenterViewerActivityEvents( @@ -423,64 +285,37 @@ export async function listTrustCenterViewerActivityEvents( return handleApiResponse(response); } -export async function listTrustCenterControlCategories( - args: z.infer, +export async function trustCenterControlCategories( + args: z.infer, ): Promise { - const { slugId, ...params } = args; - const url = buildUrl( - `/v1/trust-centers/${String(slugId)}/control-categories`, - params, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "controlCategoryId", + "control-categories", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } -export async function getTrustCenterControlCategory( - args: z.infer, +export async function trustCenterControls( + args: z.infer, ): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/control-categories/${String(args.controlCategoryId)}`, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "trustCenterControlId", + "controls", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } -export async function listTrustCenterControls( - args: z.infer, +export async function trustCenterFaqs( + args: z.infer, ): Promise { - const { slugId, ...params } = args; - const url = buildUrl(`/v1/trust-centers/${String(slugId)}/controls`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function getTrustCenterControl( - args: z.infer, -): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/controls/${String(args.trustCenterControlId)}`, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listTrustCenterFaqs( - args: z.infer, -): Promise { - const { slugId, ...params } = args; - const url = buildUrl(`/v1/trust-centers/${String(slugId)}/faqs`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function getTrustCenterFaq( - args: z.infer, -): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/faqs/${String(args.faqId)}`, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "faqId", + "faqs", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } export async function listTrustCenterResources( @@ -569,64 +404,37 @@ Note: This is a binary file. Use appropriate tools to download and process the a }; } -export async function listTrustCenterSubprocessors( - args: z.infer, +export async function trustCenterSubprocessors( + args: z.infer, ): Promise { - const { slugId, ...params } = args; - const url = buildUrl( - `/v1/trust-centers/${String(slugId)}/subprocessors`, - params, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "subprocessorId", + "subprocessors", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } -export async function getTrustCenterSubprocessor( - args: z.infer, +export async function trustCenterUpdates( + args: z.infer, ): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/subprocessors/${String(args.subprocessorId)}`, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "updateId", + "updates", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listTrustCenterUpdates( - args: z.infer, -): Promise { - const { slugId, ...params } = args; - const url = buildUrl(`/v1/trust-centers/${String(slugId)}/updates`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function getTrustCenterUpdate( - args: z.infer, -): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/updates/${String(args.updateId)}`, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listTrustCenterViewers( - args: z.infer, -): Promise { - const { slugId, ...params } = args; - const url = buildUrl(`/v1/trust-centers/${String(slugId)}/viewers`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } -export async function getTrustCenterViewer( - args: z.infer, +export async function trustCenterViewers( + args: z.infer, ): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/viewers/${String(args.viewerId)}`, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "viewerId", + "viewers", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } export async function getTrustCenterSubscriber( @@ -639,26 +447,15 @@ export async function getTrustCenterSubscriber( return handleApiResponse(response); } -export async function getTrustCenterSubscriberGroup( - args: z.infer, +export async function trustCenterSubscriberGroups( + args: z.infer, ): Promise { - const url = buildUrl( - `/v1/trust-centers/${String(args.slugId)}/subscriber-groups/${String(args.subscriberGroupId)}`, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listTrustCenterSubscriberGroups( - args: z.infer, -): Promise { - const { slugId, ...params } = args; - const url = buildUrl( - `/v1/trust-centers/${String(slugId)}/subscriber-groups`, - params, + return makeTrustCenterConsolidatedRequest( + "/v1/trust-centers", + args, + "subscriberGroupId", + "subscriber-groups", ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); } export async function listTrustCenterHistoricalAccessRequests( @@ -666,7 +463,7 @@ export async function listTrustCenterHistoricalAccessRequests( ): Promise { const { slugId, ...params } = args; const url = buildUrl( - `/v1/trust-centers/${String(slugId)}/access-requests/historical`, + `/v1/trust-centers/${String(slugId)}/historical-access-requests`, params, ); const response = await makeAuthenticatedRequest(url); @@ -689,56 +486,30 @@ export async function listTrustCenterSubscribers( export default { tools: [ { tool: GetTrustCenterTool, handler: getTrustCenter }, - { - tool: ListTrustCenterAccessRequestsTool, - handler: listTrustCenterAccessRequests, - }, - { - tool: GetTrustCenterAccessRequestTool, - handler: getTrustCenterAccessRequest, - }, + { tool: TrustCenterAccessRequestsTool, handler: trustCenterAccessRequests }, { tool: ListTrustCenterViewerActivityEventsTool, handler: listTrustCenterViewerActivityEvents, }, { - tool: ListTrustCenterControlCategoriesTool, - handler: listTrustCenterControlCategories, - }, - { - tool: GetTrustCenterControlCategoryTool, - handler: getTrustCenterControlCategory, + tool: TrustCenterControlCategoriesTool, + handler: trustCenterControlCategories, }, - { tool: ListTrustCenterControlsTool, handler: listTrustCenterControls }, - { tool: GetTrustCenterControlTool, handler: getTrustCenterControl }, - { tool: ListTrustCenterFaqsTool, handler: listTrustCenterFaqs }, - { tool: GetTrustCenterFaqTool, handler: getTrustCenterFaq }, + { tool: TrustCenterControlsTool, handler: trustCenterControls }, + { tool: TrustCenterFaqsTool, handler: trustCenterFaqs }, { tool: ListTrustCenterResourcesTool, handler: listTrustCenterResources }, { tool: GetTrustCenterDocumentTool, handler: getTrustCenterDocument }, { tool: GetTrustCenterResourceMediaTool, handler: getTrustCenterResourceMedia, }, - { - tool: ListTrustCenterSubprocessorsTool, - handler: listTrustCenterSubprocessors, - }, - { - tool: GetTrustCenterSubprocessorTool, - handler: getTrustCenterSubprocessor, - }, - { tool: ListTrustCenterUpdatesTool, handler: listTrustCenterUpdates }, - { tool: GetTrustCenterUpdateTool, handler: getTrustCenterUpdate }, - { tool: ListTrustCenterViewersTool, handler: listTrustCenterViewers }, - { tool: GetTrustCenterViewerTool, handler: getTrustCenterViewer }, + { tool: TrustCenterSubprocessorsTool, handler: trustCenterSubprocessors }, + { tool: TrustCenterUpdatesTool, handler: trustCenterUpdates }, + { tool: TrustCenterViewersTool, handler: trustCenterViewers }, { tool: GetTrustCenterSubscriberTool, handler: getTrustCenterSubscriber }, { - tool: GetTrustCenterSubscriberGroupTool, - handler: getTrustCenterSubscriberGroup, - }, - { - tool: ListTrustCenterSubscriberGroupsTool, - handler: listTrustCenterSubscriberGroups, + tool: TrustCenterSubscriberGroupsTool, + handler: trustCenterSubscriberGroups, }, { tool: ListTrustCenterHistoricalAccessRequestsTool, diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index 36d0282..6afc2dd 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -3,11 +3,9 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, + createConsolidatedSchema, createIdWithPaginationSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -15,11 +13,10 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const ListVendorsInput = createPaginationSchema(); - -const GetVendorInput = createIdSchema({ +const VendorsInput = createConsolidatedSchema({ paramName: "vendorId", description: VENDOR_ID_DESCRIPTION, + resourceName: "vendor", }); const ListVendorDocumentsInput = createIdWithPaginationSchema({ @@ -42,7 +39,7 @@ const GetVendorSecurityReviewInput = z.object({ securityReviewId: z .string() .describe( - "Security review ID to get details for, e.g. 'security-review-456'", + "Security review ID to retrieve, e.g. 'review-123' or specific security review identifier", ), }); @@ -51,37 +48,39 @@ const ListVendorSecurityReviewDocumentsInput = z.object({ securityReviewId: z .string() .describe( - "Security review ID to get documents for, e.g. 'security-review-456'", + "Security review ID to get documents for, e.g. 'review-123' or specific security review identifier", ), - ...createPaginationSchema().shape, + pageSize: z + .number() + .min(1) + .max(100) + .describe("Number of items to return per page (1-100)") + .optional(), + pageCursor: z + .string() + .describe("Cursor for pagination to get the next page of results") + .optional(), }); // 3. Tool Definitions -export const ListVendorsTool: Tool = { - name: "list_vendors", - description: - "List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors.", - parameters: ListVendorsInput, -}; - -export const GetVendorTool: Tool = { - name: "get_vendor", +export const VendorsTool: Tool = { + name: "vendors", description: - "Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from get_vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status.", - parameters: GetVendorInput, + "Access vendors in your Vanta account. Provide vendorId to get a specific vendor, or omit to list all vendors. Returns vendor details, risk levels, and management status for third-party risk assessment.", + parameters: VendorsInput, }; export const ListVendorDocumentsTool: Tool = { name: "list_vendor_documents", description: - "List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence.", + "List vendor's documents. Get all documents associated with a specific vendor for compliance and risk assessment.", parameters: ListVendorDocumentsInput, }; export const ListVendorFindingsTool: Tool = { name: "list_vendor_findings", description: - "List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor.", + "List vendor's findings. Get all security findings and compliance issues identified for a specific vendor.", parameters: ListVendorFindingsInput, }; @@ -90,7 +89,7 @@ export const ListVendorSecurityReviewsTool: Tool< > = { name: "list_vendor_security_reviews", description: - "Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities.", + "List vendor's security reviews. Get all security assessments and reviews conducted for a specific vendor.", parameters: ListVendorSecurityReviewsInput, }; @@ -99,7 +98,7 @@ export const GetVendorSecurityReviewTool: Tool< > = { name: "get_vendor_security_review", description: - "Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations.", + "Get vendor security review by ID. Retrieve detailed information about a specific security review for a vendor.", parameters: GetVendorSecurityReviewInput, }; @@ -108,21 +107,15 @@ export const ListVendorSecurityReviewDocumentsTool: Tool< > = { name: "list_vendor_security_review_documents", description: - "Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment.", + "List vendor security review's documents. Get all documents associated with a specific vendor security review.", parameters: ListVendorSecurityReviewDocumentsInput, }; // 4. Implementation Functions -export async function listVendors( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/vendors", args); -} - -export async function getVendor( - args: z.infer, +export async function vendors( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/vendors", args.vendorId); + return makeConsolidatedRequest("/v1/vendors", args, "vendorId"); } export async function listVendorDocuments( @@ -180,8 +173,7 @@ export async function listVendorSecurityReviewDocuments( // Registry export for automated tool registration export default { tools: [ - { tool: ListVendorsTool, handler: listVendors }, - { tool: GetVendorTool, handler: getVendor }, + { tool: VendorsTool, handler: vendors }, { tool: ListVendorDocumentsTool, handler: listVendorDocuments }, { tool: ListVendorFindingsTool, handler: listVendorFindings }, { tool: ListVendorSecurityReviewsTool, handler: listVendorSecurityReviews }, diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index 040dc0d..1deddfa 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -3,53 +3,38 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + makeConsolidatedRequest, } from "./common/imports.js"; // 2. Input Schemas -const ListVulnerabilitiesInput = createPaginationSchema(); - -const GetVulnerabilityInput = createIdSchema({ +const VulnerabilitiesInput = createConsolidatedSchema({ paramName: "vulnerabilityId", description: "Vulnerability ID to retrieve, e.g. 'vulnerability-123' or specific vulnerability identifier", + resourceName: "vulnerability", }); // 3. Tool Definitions -export const ListVulnerabilitiesTool: Tool = { - name: "list_vulnerabilities", - description: - "List all vulnerabilities in your Vanta account. Returns vulnerability IDs, severity levels, affected systems, and remediation status. Use this to see all identified security vulnerabilities for risk management.", - parameters: ListVulnerabilitiesInput, -}; - -export const GetVulnerabilityTool: Tool = { - name: "get_vulnerability", +export const VulnerabilitiesTool: Tool = { + name: "vulnerabilities", description: - "Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from list_vulnerabilities response. Returns complete vulnerability details including description, CVSS scores, affected assets, and remediation guidance.", - parameters: GetVulnerabilityInput, + "Access vulnerabilities in your Vanta account. Provide vulnerabilityId to get a specific vulnerability, or omit to list all vulnerabilities. Returns vulnerability details, severity levels, and status for security monitoring.", + parameters: VulnerabilitiesInput, }; // 4. Implementation Functions -export async function listVulnerabilities( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/vulnerabilities", args); -} - -export async function getVulnerability( - args: z.infer, +export async function vulnerabilities( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/vulnerabilities", args.vulnerabilityId); + return makeConsolidatedRequest( + "/v1/vulnerabilities", + args, + "vulnerabilityId", + ); } // Registry export for automated tool registration export default { - tools: [ - { tool: ListVulnerabilitiesTool, handler: listVulnerabilities }, - { tool: GetVulnerabilityTool, handler: getVulnerability }, - ], + tools: [{ tool: VulnerabilitiesTool, handler: vulnerabilities }], }; diff --git a/src/operations/vulnerable-assets.ts b/src/operations/vulnerable-assets.ts index 3245a1e..84aea87 100644 --- a/src/operations/vulnerable-assets.ts +++ b/src/operations/vulnerable-assets.ts @@ -3,54 +3,38 @@ import { CallToolResult, Tool, z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + createConsolidatedSchema, + makeConsolidatedRequest, } from "./common/imports.js"; // 2. Input Schemas -const ListVulnerableAssetsInput = createPaginationSchema(); - -const GetVulnerableAssetInput = createIdSchema({ +const VulnerableAssetsInput = createConsolidatedSchema({ paramName: "vulnerableAssetId", description: "Vulnerable asset ID to retrieve, e.g. 'vulnerable-asset-123' or specific asset identifier", + resourceName: "vulnerable asset", }); // 3. Tool Definitions -export const ListVulnerableAssetsTool: Tool = - { - name: "list_vulnerable_assets", - description: - "List all vulnerable assets in your Vanta account. Returns asset IDs, hostnames, vulnerability counts, and risk scores for security monitoring. Use this to see all assets that have identified vulnerabilities requiring attention.", - parameters: ListVulnerableAssetsInput, - }; - -export const GetVulnerableAssetTool: Tool = { - name: "get_vulnerable_asset", +export const VulnerableAssetsTool: Tool = { + name: "vulnerable_assets", description: - "Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from list_vulnerable_assets response. Returns complete asset details including vulnerability list, risk assessment, and remediation recommendations.", - parameters: GetVulnerableAssetInput, + "Access vulnerable assets in your Vanta account. Provide vulnerableAssetId to get a specific vulnerable asset, or omit to list all vulnerable assets. Returns asset details, vulnerability counts, and security status.", + parameters: VulnerableAssetsInput, }; // 4. Implementation Functions -export async function listVulnerableAssets( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/vulnerable-assets", args); -} - -export async function getVulnerableAsset( - args: z.infer, +export async function vulnerableAssets( + args: z.infer, ): Promise { - return makeGetByIdRequest("/v1/vulnerable-assets", args.vulnerableAssetId); + return makeConsolidatedRequest( + "/v1/vulnerable-assets", + args, + "vulnerableAssetId", + ); } // Registry export for automated tool registration export default { - tools: [ - { tool: ListVulnerableAssetsTool, handler: listVulnerableAssets }, - { tool: GetVulnerableAssetTool, handler: getVulnerableAsset }, - ], + tools: [{ tool: VulnerableAssetsTool, handler: vulnerableAssets }], }; From 8013331d3495b5b098ca9c03d5236c29982904c8 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Fri, 26 Sep 2025 13:07:11 -0400 Subject: [PATCH 22/24] Perform more consolidation to bring the tool count under control --- README.md | 221 ++++--- src/eval/eval.ts | 112 +--- src/operations/README.md | 847 +++++++------------------- src/operations/common/descriptions.ts | 3 + src/operations/discovered-vendors.ts | 8 +- src/operations/documents.ts | 92 ++- src/operations/integrations.ts | 219 ++++--- src/operations/vendors.ts | 108 ++-- 8 files changed, 542 insertions(+), 1068 deletions(-) diff --git a/README.md b/README.md index 14fa840..545f8dc 100644 --- a/README.md +++ b/README.md @@ -25,33 +25,27 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid ### Discovered Vendors -- List vendors automatically discovered through integrations for potential vendor onboarding -- Access detailed account information for discovered vendors including integration sources -- Understand vendor relationships and account structures before converting to managed vendors -- Streamline vendor risk assessment workflows by identifying unmanaged vendor relationships +- Identify unmanaged vendors detected by Vanta's discovery engine +- Review automatically discovered vendor profiles before they are confirmed as managed vendors +- Inspect accounts associated with a discovered vendor to understand potential risk exposure -| Tool Name | Description | -| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. | -| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors identified by Vanta's automated discovery. Returns vendor names, domains, discovery sources, and linkage status to managed vendor records. | +| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List accounts associated with a discovered vendor. Provide discoveredVendorId to retrieve account identifiers, connection details, and discovery metadata. | ### Documents - List all documents in your Vanta account for compliance and evidence management - Get detailed information about specific documents including metadata and compliance mappings -- View security controls that are mapped to or associated with documents as evidence -- Access external links and references associated with documents -- List all files and uploads attached to documents for compliance documentation +- Access document-related resources including controls, links, and uploads through intelligent consolidation - Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata -| Tool Name | Description | -| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| [`documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. | -| [`documents`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. | -| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. | -| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. | -| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. | -| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload with automatic MIME type handling. | +| Tool Name | Description | +| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`documents`](https://developer.vanta.com/reference/listdocuments) | Access documents in your Vanta account. Provide documentId to get a specific document, or omit to list all documents. Returns document IDs, names, types, and metadata for compliance and evidence management. | +| [`document_resources`](https://developer.vanta.com/reference/listdocumentcontrols) | Access document-related resources including controls, links, and uploads. Specify resourceType ('controls', 'links', 'uploads') to get the specific type of resource associated with a document. | +| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download document file by upload ID. Get the actual uploaded document file. Intelligently handles different MIME types: returns text content for readable files, metadata information for binary files. | ### Frameworks @@ -82,21 +76,13 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all connected integrations in your Vanta account (AWS, Azure, GCP, Snyk, etc.) - Get detailed information about specific integrations and their configurations -- View integration resource kinds and connection status +- Access integration resources including resource kinds, resource details, and specific resources through intelligent consolidation - Monitor which integrations are actively connected to your instance -- List resource types (kinds) that integrations can monitor (S3Bucket, CloudwatchLogGroup, etc.) -- Get detailed information about specific resource types and their properties -- List all infrastructure resources discovered by integrations -- Access detailed resource information including metadata, compliance status, and configuration - -| Tool Name | Description | -| ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist. | -| [`integrations`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. | -| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. | -| [`integrations_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. | -| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. | -| [`integrations_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. | + +| Tool Name | Description | +| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`integrations`](https://developer.vanta.com/reference/listintegrations) | Access connected integrations in your Vanta account. Provide integrationId to get a specific integration, or omit to list all integrations. Returns integration details, supported resource kinds, and connection status for compliance monitoring. | +| [`integration_resources`](https://developer.vanta.com/reference/listresourcekindsummaries) | Access integration resources including resource kinds, resource kind details, and specific resources. Specify operation ('list_kinds', 'get_kind_details', 'list_resources', 'get_resource') to perform the desired action. | ### Monitored Computers @@ -208,23 +194,16 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid - List all vendors in your Vanta account for vendor risk management - Get detailed vendor information including contact details and website URLs -- Access vendor risk assessment status and compliance information +- Access vendor compliance data including documents, findings, and security reviews through intelligent consolidation - Manage vendor relationships and due diligence tracking -- View all documents associated with vendors for compliance purposes -- Access security findings and risk assessment results for vendors -- Review history of security assessments and due diligence activities -- Get detailed information about specific vendor security reviews -- Access supporting documentation and reports for security assessments - -| Tool Name | Description | -| ----------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | -| [`vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. | -| [`vendors`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. | -| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. | -| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. | -| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. | -| [`vendors_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. | -| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. | +- Review history of security assessments and due diligence activities through consolidated access + +| Tool Name | Description | +| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`vendors`](https://developer.vanta.com/reference/listvendors) | Access vendors in your Vanta account. Provide vendorId to get a specific vendor, or omit to list all vendors. Returns vendor details, risk levels, and management status for third-party risk assessment. | +| [`vendor_compliance`](https://developer.vanta.com/reference/listvendordocuments) | Access vendor compliance data including documents, findings, and security reviews. Specify complianceType ('documents', 'findings', 'security_reviews') to get the specific type of compliance information for a vendor. | +| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get vendor security review by ID. Retrieve detailed information about a specific security review for a vendor. | +| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | List vendor security review's documents. Get all documents associated with a specific vendor security review. | ### Vulnerabilities @@ -262,69 +241,58 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid ## Tools -| Tool Name | Description | -| ----------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | -| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | -| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | -| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | -| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | -| [`frameworks`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | -| [`controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | -| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | -| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from controls which lists controls already in your account - this shows available controls you can implement. | -| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | -| [`controls`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | -| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | -| [`risks`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | -| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | -| [`integrations`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | -| [`list_integration_resource_kinds`](https://developer.vanta.com/reference/listresourcekindsummaries) | List integration resource kinds. Lists a connected integration's resource types (kinds) such as S3Bucket, CloudwatchLogGroup, etc. Use this to see what types of resources an integration can monitor. | -| [`integrations_resource_kind_details`](https://developer.vanta.com/reference/getresourcekinddetails) | Get details for resource kind. Gets details for a specific resource type (kind) such as S3Bucket or CloudwatchLogGroup for a specific integration. Use this to understand what properties and metadata are available for a resource type. | -| [`list_integration_resources`](https://developer.vanta.com/reference/listresources) | List resources. List all resources discovered by a specific integration. Use this to see all infrastructure resources that Vanta is monitoring through an integration. | -| [`integrations_resource`](https://developer.vanta.com/reference/getresource) | Get resource by ID. Retrieve detailed information about a specific resource discovered by an integration. Use this to get full details about infrastructure resources including metadata, compliance status, and configuration. | -| [`vendors`](https://developer.vanta.com/reference/listvendors) | List all vendors in your Vanta account. Returns vendor IDs, names, website URLs, and many other vendor attributes. Use this to see all existing vendors. | -| [`vendors`](https://developer.vanta.com/reference/getvendor) | Get vendor by ID. Retrieve detailed information about a specific vendor when its ID is known. The ID of a vendor can be found from vendors response. Returns complete vendor details including name, website URLs, contact information, and risk assessment status. | -| [`list_vendor_documents`](https://developer.vanta.com/reference/listvendordocuments) | List vendor documents. Get all documents associated with a specific vendor for compliance and risk assessment purposes. Use this to see what documentation is available for vendor due diligence. | -| [`list_vendor_findings`](https://developer.vanta.com/reference/listvendorfindings) | List vendor findings. Get all security findings and risk assessment results for a specific vendor. Use this to understand security concerns and compliance issues related to a vendor. | -| [`list_vendor_security_reviews`](https://developer.vanta.com/reference/getsecurityreviewsbyvendorid) | Get security reviews by vendor ID. List all security reviews conducted for a specific vendor. Use this to see the history of security assessments and due diligence activities. | -| [`vendors_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | -| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | Get security review documents. List all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | -| [`documents`](https://developer.vanta.com/reference/listdocuments) | List all documents in your Vanta account. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | -| [`documents`](https://developer.vanta.com/reference/getdocument) | Get document by ID. Retrieve detailed information about a specific document when its ID is known. The ID of a document can be found from documents response. Returns complete document details including name, type, metadata, and compliance mappings. | -| [`list_document_controls`](https://developer.vanta.com/reference/listdocumentcontrols) | List document's controls. Get all security controls that are mapped to or associated with a specific document. Use this to understand which compliance controls are supported by a particular document as evidence. | -| [`list_document_links`](https://developer.vanta.com/reference/listdocumentlinks) | List document's links. Get all external links and references associated with a specific document. Use this to access related resources, external documentation, or supplementary materials for compliance evidence. | -| [`list_document_uploads`](https://developer.vanta.com/reference/listdocumentuploads) | List document's uploads. Get all files and uploads that have been attached to a specific document. Use this to see what files are available for download or review as part of compliance documentation. | -| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download file for document. Intelligently retrieves file content from a document upload. For text-based files (txt, json, csv, xml, etc.), returns the readable content. For binary files (images, PDFs, etc.), returns file metadata and information. Use this to access compliance evidence and documentation content that can be analyzed. | -| [`policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | -| [`policies`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. The ID of a policy can be found from policies response. Returns complete policy details including name, description, content, approval status, and compliance mappings. | -| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors in your Vanta account. Returns vendors that have been automatically discovered through integrations but may not yet be managed as official vendors. Use this to see potential vendors for risk assessment and vendor management onboarding. | -| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List discovered vendor accounts in your Vanta account. Returns detailed account information for discovered vendors including integration sources and account metadata. Use this to understand vendor relationships and account structures before converting to managed vendors. | -| [`groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | -| [`groups`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from groups response. Returns complete group details including name, description, member count, and access permissions. | -| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | -| [`people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | -| [`people`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from people response. Returns complete person details including name, email, role, group memberships, and access permissions. | -| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | -| [`vulnerabilities`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | -| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | -| [`vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | -| [`vulnerable_assets`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | -| [`monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | -| [`monitored_computers`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | -| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | -| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | -| [`trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | -| [`trust_center_access_requests`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | -| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | -| [`trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | -| [`trust_center_control_categories`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | -| [`trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | -| [`trust_center_controls`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | -| [`trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | -| [`trust_center_faqs`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | -| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | -| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | +| Tool Name | Description | +| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | +| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | +| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | +| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | +| [`frameworks`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | +| [`controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | +| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from controls which lists controls already in your account - this shows available controls you can implement. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | +| [`controls`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | +| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | +| [`risks`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | +| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | +| [`integrations`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | +| [`integration_resources`](https://developer.vanta.com/reference/listresourcekindsummaries) | Access integration resources including resource kinds, resource kind details, and specific resources. Specify operation ('list_kinds', 'get_kind_details', 'list_resources', 'get_resource') to perform the desired action. Use this to explore what resources an integration can monitor and access detailed resource information. | +| [`vendor_compliance`](https://developer.vanta.com/reference/listvendordocuments) | Access vendor compliance data including documents, findings, and security reviews. Specify complianceType ('documents', 'findings', 'security_reviews') to get the specific type of compliance information for a vendor. Use this to explore vendor compliance documentation, security findings, and assessment history. | +| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get vendor security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | +| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | List vendor security review's documents. Get all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | +| [`documents`](https://developer.vanta.com/reference/listdocuments) | Access documents in your Vanta account. Provide documentId to get a specific document, or omit to list all documents. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | +| [`document_resources`](https://developer.vanta.com/reference/listdocumentcontrols) | Access document-related resources including controls, links, and uploads. Specify resourceType ('controls', 'links', 'uploads') to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached. | +| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download document file by upload ID. Get the actual uploaded document file. Intelligently handles different MIME types: returns text content for readable files, metadata information for binary files. Use this to access compliance evidence and documentation content that can be analyzed. | +| [`policies`](https://developer.vanta.com/reference/listpolicies) | Access policies in your Vanta account. Provide policyId to get a specific policy, or omit to list all policies. Returns policy IDs, names, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | +| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors identified by Vanta's automated discovery. Returns vendor names, domains, discovery sources, and linkage status to managed vendor records. | +| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List accounts associated with a discovered vendor. Provide discoveredVendorId to retrieve account identifiers, connection details, and discovery metadata. | +| [`groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | +| [`groups`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from groups response. Returns complete group details including name, description, member count, and access permissions. | +| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | +| [`people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | +| [`people`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from people response. Returns complete person details including name, email, role, group memberships, and access permissions. | +| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | +| [`vulnerabilities`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | +| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | +| [`vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | +| [`vulnerable_assets`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | +| [`monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | +| [`monitored_computers`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | +| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | +| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | +| [`trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | +| [`trust_center_access_requests`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | +| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | +| [`trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | +| [`trust_center_control_categories`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | +| [`trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | +| [`trust_center_controls`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | +| [`trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | +| [`trust_center_faqs`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | +| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | +| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | ## Configuration @@ -466,8 +434,10 @@ vanta-mcp-server/ │ │ ├── frameworks.ts # Framework-related operations │ │ ├── risks.ts # Risk scenario operations │ │ ├── tests.ts # Test-related operations +│ │ ├── integrations.ts # Integration-related operations (consolidated) +│ │ ├── discovered-vendors.ts # Discovery operations (consolidated) │ │ ├── trust-centers.ts # Trust Center operations -│ │ └── ... # Other resource operations (17 total) +│ │ └── ... # Other resource operations (18 total) │ ├── eval/ # Evaluation and testing framework │ │ ├── eval.ts # LLM evaluation test cases │ │ └── README.md # Evaluation documentation @@ -482,12 +452,37 @@ vanta-mcp-server/ ### Architecture Highlights +- **Consolidated Tool Pattern**: Single tools intelligently handle both list and get operations with optional ID parameters +- **Reduced Complexity**: 43 tools (down from 53) through smart consolidation while maintaining full functionality - **Clean Organization**: Operations files are cleanly separated from infrastructure code - **Common Subdirectory**: All shared utilities, imports, and descriptions are organized in `operations/common/` - **Automated Registry**: New tools are automatically discovered and registered without manual configuration - **DRY Principles**: Extensive code reuse through centralized utilities and schema factories - **Type Safety**: Full TypeScript coverage with comprehensive type definitions +### Intelligent Tool Consolidation + +The Vanta MCP Server implements a **consolidated tool architecture** where many tools can handle both list and get operations: + +**Before (53 tools):** + +- `list_document_controls`, `list_document_links`, `list_document_uploads` (3 separate tools) +- `list_integration_resource_kinds`, `get_integration_resource_kind_details`, `list_integration_resources`, `get_integration_resource` (4 separate tools) +- `list_vendor_documents`, `list_vendor_findings`, `list_vendor_security_reviews` (3 separate tools) + +**After (43 tools):** + +- `document_resources` (consolidates 3 operations with `resourceType` parameter) +- `integration_resources` (consolidates 4 operations with `operation` parameter) +- `vendor_compliance` (consolidates 3 operations with `complianceType` parameter) + +**Benefits:** + +- ✅ **Fewer Tools**: 19% reduction while maintaining all functionality +- ✅ **Clearer Intent**: Tools match natural language patterns better +- ✅ **Preserved Usability**: All original capabilities maintained +- ✅ **Intelligent Routing**: Single tool automatically routes to appropriate endpoints + For detailed architecture documentation, see [`src/operations/README.md`](src/operations/README.md). ## Debugging diff --git a/src/eval/eval.ts b/src/eval/eval.ts index 882f974..ccdf6f2 100644 --- a/src/eval/eval.ts +++ b/src/eval/eval.ts @@ -16,22 +16,15 @@ import { RisksTool, // Integrations IntegrationsTool, - ListIntegrationResourceKindsTool, - GetIntegrationResourceKindDetailsTool, - ListIntegrationResourcesTool, - GetIntegrationResourceTool, + IntegrationResourcesTool, // Vendors VendorsTool, - ListVendorDocumentsTool, - ListVendorFindingsTool, - ListVendorSecurityReviewsTool, + VendorComplianceTool, GetVendorSecurityReviewTool, ListVendorSecurityReviewDocumentsTool, // Documents DocumentsTool, - ListDocumentControlsTool, - ListDocumentLinksTool, - ListDocumentUploadsTool, + DocumentResourcesTool, DownloadDocumentFileTool, // Policies PoliciesTool, @@ -157,35 +150,9 @@ const tools = [ { type: "function" as const, function: { - name: ListIntegrationResourceKindsTool.name, - description: ListIntegrationResourceKindsTool.description, - parameters: zodToJsonSchema(ListIntegrationResourceKindsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetIntegrationResourceKindDetailsTool.name, - description: GetIntegrationResourceKindDetailsTool.description, - parameters: zodToJsonSchema( - GetIntegrationResourceKindDetailsTool.parameters, - ), - }, - }, - { - type: "function" as const, - function: { - name: ListIntegrationResourcesTool.name, - description: ListIntegrationResourcesTool.description, - parameters: zodToJsonSchema(ListIntegrationResourcesTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: GetIntegrationResourceTool.name, - description: GetIntegrationResourceTool.description, - parameters: zodToJsonSchema(GetIntegrationResourceTool.parameters), + name: IntegrationResourcesTool.name, + description: IntegrationResourcesTool.description, + parameters: zodToJsonSchema(IntegrationResourcesTool.parameters), }, }, { @@ -199,25 +166,9 @@ const tools = [ { type: "function" as const, function: { - name: ListVendorDocumentsTool.name, - description: ListVendorDocumentsTool.description, - parameters: zodToJsonSchema(ListVendorDocumentsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListVendorFindingsTool.name, - description: ListVendorFindingsTool.description, - parameters: zodToJsonSchema(ListVendorFindingsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListVendorSecurityReviewsTool.name, - description: ListVendorSecurityReviewsTool.description, - parameters: zodToJsonSchema(ListVendorSecurityReviewsTool.parameters), + name: VendorComplianceTool.name, + description: VendorComplianceTool.description, + parameters: zodToJsonSchema(VendorComplianceTool.parameters), }, }, { @@ -249,25 +200,9 @@ const tools = [ { type: "function" as const, function: { - name: ListDocumentControlsTool.name, - description: ListDocumentControlsTool.description, - parameters: zodToJsonSchema(ListDocumentControlsTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListDocumentLinksTool.name, - description: ListDocumentLinksTool.description, - parameters: zodToJsonSchema(ListDocumentLinksTool.parameters), - }, - }, - { - type: "function" as const, - function: { - name: ListDocumentUploadsTool.name, - description: ListDocumentUploadsTool.description, - parameters: zodToJsonSchema(ListDocumentUploadsTool.parameters), + name: DocumentResourcesTool.name, + description: DocumentResourcesTool.description, + parameters: zodToJsonSchema(DocumentResourcesTool.parameters), }, }, { @@ -508,6 +443,22 @@ export const testCases = [ expectedParams: {}, description: "Should call frameworks to list available frameworks", }, + { + prompt: + "Show me all discovered vendors flagged by Vanta's discovery engine", + expectedTool: "list_discovered_vendors", + expectedParams: {}, + description: + "Should call list_discovered_vendors to list all discovered vendors", + }, + { + prompt: + "Show the accounts associated with discovered vendor discovered-vendor-123", + expectedTool: "list_discovered_vendor_accounts", + expectedParams: { discoveredVendorId: "discovered-vendor-123" }, + description: + "Should call list_discovered_vendor_accounts with discoveredVendorId for vendor accounts", + }, { prompt: "What is the current % status of my SOC 2?", expectedTool: "frameworks", @@ -604,13 +555,6 @@ export const testCases = [ description: "Should call documents with documentId for specific document details", }, - { - prompt: - "Show me all the policies we have established for our organization.", - expectedTool: "policies", - expectedParams: {}, - description: "Should call policies to list all organizational policies", - }, { prompt: "I need to review the details of our data retention policy with ID POLICY-789.", diff --git a/src/operations/README.md b/src/operations/README.md index 8a265a0..af800d4 100644 --- a/src/operations/README.md +++ b/src/operations/README.md @@ -1,730 +1,311 @@ -# Operations Architecture Guide +# Operations Architecture Reference -This document explains the architecture, patterns, and conventions used in the Vanta MCP Server operations layer. - -## Table of Contents - -- [Overview](#overview) -- [File Structure](#file-structure) -- [Naming Conventions](#naming-conventions) -- [DRY Utilities](#dry-utilities) -- [Schema Factory Functions](#schema-factory-functions) -- [Request Handler Utilities](#request-handler-utilities) -- [Automated Tool Registry System](#automated-tool-registry-system) -- [Creating New Operations](#creating-new-operations) -- [Best Practices](#best-practices) -- [Examples](#examples) +This document explains the structure, conventions, and utilities used in the Vanta MCP Server operations layer. It is intended for developers extending the `src/operations/` directory. ## Overview -The operations layer provides a clean, consistent interface to the Vanta API. Each operation file corresponds to a specific resource type in the Vanta API (e.g., `controls.ts`, `vendors.ts`, `people.ts`). - -### Key Architectural Principles - -1. **DRY (Don't Repeat Yourself)**: Common patterns are abstracted into reusable utilities -2. **Consolidated Tool Pattern**: Single tools intelligently handle both list and get operations -3. **Type Safety**: Full TypeScript support with proper type definitions -4. **Consistent Error Handling**: Standardized error responses across all operations -5. **Schema Factories**: Reusable Zod schema generators for common patterns -6. **Automated Registry**: Zero-maintenance tool registration system - -### Consolidated Tool Architecture - -The operations layer implements a **consolidated tool pattern** where a single tool can intelligently handle both listing multiple resources and retrieving a single resource by ID. This approach provides significant benefits: - -#### Benefits of Consolidation - -- **Improved LLM Experience**: Reduces cognitive load by providing fewer, more intuitive tools -- **Clearer Intent Mapping**: Tools match natural language patterns ("I want controls" vs "I want to list controls") -- **Reduced API Surface**: Fewer tools to learn, document, and maintain -- **Intelligent Routing**: Single tool automatically routes to appropriate endpoints based on parameters -- **Preserved Functionality**: All original capabilities maintained with enhanced usability +- **Purpose**: Each operations file wraps one or more Vanta API GET endpoints as MCP tools. +- **Scope**: Operation modules and registered tools. +- **Patterns**: Consolidated list/get tools, resource-specific routing tools, and specialized tools for unique behaviors (e.g., downloads). +- **Automation**: Tools are auto-registered through the registry system; common logic lives in `src/operations/common/`. -#### How It Works +## Directory Layout -```typescript -// Single tool handles multiple scenarios -await controls({}); // Lists all controls -await controls({ controlId: "control-123" }); // Gets specific control -await controls({ frameworkMatchesAny: ["soc2"] }); // Filtered listing - -// Trust Center tools include required slugId -await trust_center_faqs({ slugId: "company" }); // Lists FAQs -await trust_center_faqs({ slugId: "company", faqId: "faq-123" }); // Gets specific FAQ ``` - -The consolidation pattern uses optional ID parameters - when an ID is provided, the tool retrieves that specific resource; when omitted, it lists all resources with optional filtering and pagination. - -## File Structure - -``` -operations/ -├── README.md # This file -├── index.ts # Barrel export for all operations -├── common/ # Shared utilities and common files -│ ├── descriptions.ts # Centralized parameter descriptions -│ ├── imports.ts # Centralized common imports for operations -│ └── utils.ts # DRY utilities and common functions -├── controls.ts # Control-related operations -├── vendors.ts # Vendor-related operations -├── people.ts # People-related operations -└── ... # Other resource operations +src/operations/ +├── README.md # Operations reference (this file) +├── README.proposed.md # Proposal used for the latest refresh +├── index.ts # Barrel export of all operations modules +├── common/ +│ ├── descriptions.ts # Reusable parameter descriptions (e.g., DOCUMENT_ID_DESCRIPTION) +│ ├── imports.ts # Barrel import for CallToolResult, Tool, z, utilities, constants +│ └── utils.ts # Shared schema factories, request helpers, response handlers +├── documents.ts # Document tools (consolidated + download) +├── frameworks.ts # Framework tools (consolidated + nested resources) +├── controls.ts +├── discovered-vendors.ts +├── ... ``` -### Standard Operation File Structure +## Core Concepts -Each operation file follows this pattern: +### Consolidated Tool Pattern -```typescript -// 1. Imports -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; -import { list of DRY utilities } from "./utils.js"; -// This is now available through common-imports.js +Many resources expose both “list” and “get by ID” behaviors within a single tool. The helper `createConsolidatedSchema` creates a schema with an optional ID plus pagination fields, and `makeConsolidatedRequest` routes the request based on the presence of that ID. -// 2. Input Schemas (using schema factories) -const ListResourcesInput = createPaginationSchema(); -const GetResourceInput = createIdSchema("resourceId", RESOURCE_ID_DESCRIPTION); +Example (`frameworks.ts`): -// 3. Tool Definitions -export const ListResourcesTool: Tool = { - name: "list_resources", - description: "...", - parameters: ListResourcesInput, -}; +```typescript +const FrameworksInput = createConsolidatedSchema({ + paramName: "frameworkId", + description: FRAMEWORK_ID_DESCRIPTION, + resourceName: "framework", +}); -// 4. Implementation Functions (using request handlers) -export async function listResources( - args: z.infer, +export async function frameworks( + args: z.infer, ): Promise { - return makePaginatedGetRequest("/v1/resources", args); + return makeConsolidatedRequest("/v1/frameworks", args, "frameworkId"); } - -// 5. Registry Export (REQUIRED for auto-registration) -export default { - tools: [ - { tool: ListResourcesTool, handler: listResources }, - { tool: GetResourceTool, handler: getResource }, - ], -}; -``` - -## Naming Conventions - -### REST-Style Tool Names - -- **`list_*`**: Returns multiple items (e.g., `list_controls`, `list_vendors`) -- **`get_*`**: Returns a single item by ID (e.g., `get_control`, `get_vendor`) -- **Special actions**: Keep descriptive names (e.g., `download_document_file`) - -### Consistent Naming Pattern - -```typescript -// ✅ Correct -const ListControlsInput = createPaginationSchema(); -export const ListControlsTool: Tool = { name: "list_controls", ... }; -export async function listControls(args: z.infer): Promise { ... } - -// ✅ Correct -const GetControlInput = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); -export const GetControlTool: Tool = { name: "get_control", ... }; -export async function getControl(args: z.infer): Promise { ... } ``` -### Function and Constant Naming - -- **Input schemas**: `List*Input`, `Get*Input` -- **Tool exports**: `List*Tool`, `Get*Tool` -- **Implementation functions**: `list*()`, `get*()` - -## DRY Utilities +- **No ID provided** → lists frameworks with pagination. +- **ID provided** → fetches a specific framework. -### Barrel Export Pattern +### Resource-Specific Routing Tools -**Location**: `src/operations/index.ts` +Some resources expose additional nested endpoints. These tools accept a required ID plus a discriminator to route to different endpoints. -We use a barrel export pattern to provide a single entry point for importing all tools and utilities: +Example (`documents.ts`): ```typescript -// Single import for all operations tools -import { - ListControlsTool, - GetControlTool, - ListRisksTool, - // ... all other tools -} from "./operations/index.js"; - -// Instead of multiple individual imports: -// import { ListControlsTool } from "./operations/controls.js"; -// import { ListRisksTool } from "./operations/risks.js"; -// ... dozens more import statements -``` - -**Benefits:** - -- ✅ Single source of truth for operations exports -- ✅ Better organization with commented sections -- ✅ Easier refactoring and maintenance -- ✅ Auto-completion works seamlessly - -### Common Imports Pattern - -**Location**: `src/operations/common/imports.ts` - -For operations files themselves, we use a common imports barrel to reduce repetitive import statements: - -```typescript -// Before: Multiple separate imports in each operations file -import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; -import { Tool } from "../types.js"; -import { z } from "zod"; -import { - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, -} from "./utils.js"; - -// After: Single consolidated import -import { - CallToolResult, - Tool, - z, - createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, -} from "./common/imports.js"; -``` - -**Benefits:** - -- ✅ Reduces import clutter in operations files -- ✅ Ensures consistency across all operations -- ✅ Single source of truth for common dependencies -- ✅ Easier to add new common utilities -- ✅ Better maintainability when dependencies change - -### Utility Functions - -The `utils.ts` file provides reusable utilities to eliminate code duplication: - -### Response Processing - -```typescript -// Standard error response -export function createErrorResponse(statusText: string): CallToolResult; - -// Standard success response with JSON -export async function createSuccessResponse( - response: Response, -): Promise; - -// Complete response handling (error or success) -export async function handleApiResponse( - response: Response, -): Promise; -``` - -### URL Construction - -```typescript -// Build URLs with query parameters -export function buildUrl( - basePath: string, - params: Record, -): string; - -// Build resource-by-ID URLs -export function buildResourceUrl(resource: string, id: string): string; -``` - -### Authentication +const DocumentResourcesInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + resourceType: z + .enum(["controls", "links", "uploads"]) + .describe( + "Type of document resource: 'controls' for associated controls, 'links' for external references, 'uploads' for attached files", + ), + ...createPaginationSchema().shape, +}); -```typescript -// Make authenticated requests to Vanta API -export async function makeAuthenticatedRequest( - url: string, - options?: RequestInit, -): Promise; +export async function documentResources( + args: z.infer, +): Promise { + const { documentId, resourceType, ...params } = args; + const endpoints = { + controls: `/v1/documents/${String(documentId)}/controls`, + links: `/v1/documents/${String(documentId)}/links`, + uploads: `/v1/documents/${String(documentId)}/uploads`, + }; + const url = buildUrl(endpoints[resourceType], params); + const response = await makeAuthenticatedRequest(url); + return handleApiResponse(response); +} ``` -## Schema Factory Functions +### Specialized Tools -Common parameter patterns are abstracted into reusable schema generators: +When behavior diverges from JSON-based responses (e.g., file downloads), tools implement custom response logic. -### Basic Schemas +Example (`documents.ts`): ```typescript -// Pagination parameters (pageSize, pageCursor) -const schema = createPaginationSchema(); - -// Single ID parameter -const schema = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); - -// ID + pagination parameters -const schema = createIdWithPaginationSchema("vendorId", VENDOR_ID_DESCRIPTION); - -// Base schema with custom fields -const schema = createFilterSchema({ - categoryMatchesAny: z.array(z.string()).optional(), +const DownloadDocumentFileInput = z.object({ + uploadedFileId: z + .string() + .describe( + "Uploaded file ID to download, e.g. 'upload-123' or specific uploaded file identifier", + ), }); -``` - -### Extended Schemas - -```typescript -// Extend pagination with custom fields -const ListControlsInput = createPaginationSchema().extend({ - frameworkMatchesAny: z - .array(z.string()) - .describe("Framework IDs to filter by") - .optional(), -}); -``` -## Request Handler Utilities - -Common request patterns are abstracted into reusable functions: - -### Simple GET Request - -```typescript -export async function listResources( - args: z.infer, +export async function downloadDocumentFile( + args: z.infer, ): Promise { - return makePaginatedGetRequest("/v1/resources", args); -} -``` - -### GET by ID + const url = buildUrl( + `/v1/document-uploads/${String(args.uploadedFileId)}/download`, + ); + const response = await makeAuthenticatedRequest(url); -```typescript -export async function getResource( - args: z.infer, -): Promise { - return makeGetByIdRequest("resources", args.resourceId); + if (!response.ok) { + return handleApiResponse(response); + } + + const contentType = + response.headers.get("content-type") ?? "application/octet-stream"; + const contentLength = response.headers.get("content-length"); + + if ( + contentType.startsWith("text/") || + contentType.includes("application/json") || + contentType.includes("application/xml") || + contentType.includes("application/javascript") || + contentType.includes("application/csv") || + contentType.includes("text/csv") + ) { + const textContent = await response.text(); + return { + content: [ + { + type: "text" as const, + text: `Document File Content (${contentType}):\n\n${textContent}`, + }, + ], + }; + } + + return { + content: [ + { + type: "text" as const, + text: `Document File Information:\n- Content Type: ${contentType}\n- Content Length: ${contentLength ? `${contentLength} bytes` : "Unknown"}\n- File Type: ${contentType.startsWith("image/") ? "Image" : contentType.startsWith("video/") ? "Video" : contentType.startsWith("audio/") ? "Audio" : contentType.startsWith("application/pdf") ? "PDF Document" : "Binary File"}\n- Upload ID: ${String(args.uploadedFileId)}\n\nNote: This is a binary file. Use appropriate tools to download and process the actual file content.`, + }, + ], + }; } ``` -### Custom Endpoints +## Shared Infrastructure (`common/`) -```typescript -export async function listResourceDetails( - args: z.infer, -): Promise { - const { resourceId, ...params } = args; - const url = buildUrl(`/v1/resources/${String(resourceId)}/details`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} -``` +### `descriptions.ts` -## Creating New Operations +- Contains reusable strings for parameter descriptions (e.g., `DOCUMENT_ID_DESCRIPTION`, `FRAMEWORK_ID_DESCRIPTION`). +- Promotes consistency and reduces duplication of descriptive text across operation files. -### Step 1: Create the Operation File +### `imports.ts` + +- Re-exports `CallToolResult`, `Tool`, `z`, schema factories, request helpers, and description constants. +- Imported by every operations file so that a single statement brings in all required utilities: ```typescript -// src/operations/new-resource.ts import { CallToolResult, Tool, z, + createConsolidatedSchema, createPaginationSchema, - createIdSchema, - makePaginatedGetRequest, - makeGetByIdRequest, + makeConsolidatedRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, + DOCUMENT_ID_DESCRIPTION, } from "./common/imports.js"; - -// All utilities, descriptions, and core imports are now available -// through the common/imports.js barrel export (located in common/ subdirectory) - -// Define schemas -const ListNewResourcesInput = createPaginationSchema(); -const GetNewResourceInput = createIdSchema( - "newResourceId", - "New resource ID to retrieve", -); - -// Define tools -export const ListNewResourcesTool: Tool = { - name: "list_new_resources", - description: "List all new resources in your Vanta account.", - parameters: ListNewResourcesInput, -}; - -export const GetNewResourceTool: Tool = { - name: "get_new_resource", - description: "Get new resource by ID.", - parameters: GetNewResourceInput, -}; - -// Implement functions -export async function listNewResources( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/new-resources", args); -} - -export async function getNewResource( - args: z.infer, -): Promise { - return makeGetByIdRequest("/v1/new-resources", args.newResourceId); -} - -// Registry export for automated tool registration -export default { - tools: [ - { tool: ListNewResourcesTool, handler: listNewResources }, - { tool: GetNewResourceTool, handler: getNewResource }, - ], -}; ``` -### Step 2: Add to Barrel Export +### `utils.ts` -Update `src/operations/index.ts` to include your new operations file: - -```typescript -// Add your new operations file to the barrel export -export * from "./tests.js"; -export * from "./frameworks.js"; -export * from "./controls.js"; -// ... existing exports ... -export * from "./new-resource.js"; // ← Add this line - -// Common utilities and shared resources -export * from "./common/utils.js"; -export * from "./common/descriptions.js"; -export * from "./common/imports.js"; -``` +Key exports include: -This ensures your tools are available through the centralized import pattern. +- **Schema factories**: `createConsolidatedSchema`, `createPaginationSchema`, `createIdSchema`, `createIdWithPaginationSchema`, `createFilterSchema`. +- **Request helpers**: `makeConsolidatedRequest`, `makePaginatedGetRequest`, `makeGetByIdRequest`, `makeSimpleGetRequest`. +- **URL utilities**: `buildUrl` for query string construction. +- **Response utilities**: `handleApiResponse`, `createErrorResponse`, `createSuccessResponse`. -### Step 3: Verify Registry Export +All utilities enforce consistent error handling and response formatting across tools. -Ensure your operations file includes the required registry export: +## Anatomy of an Operations File -```typescript -// At the end of your operations file -export default { - tools: [ - { tool: ListNewResourcesTool, handler: listNewResources }, - { tool: GetNewResourceTool, handler: getNewResource }, - // Add all tools from this file here - ], -}; -``` +Each operations file follows a common structure: -**That's it!** Your tools will be automatically registered when the server starts. No changes to `index.ts` are needed. +1. **Imports** from `./common/imports.js` for all dependencies. +2. **Input schemas** using schema factories or explicit Zod objects. +3. **Tool definitions** exporting REST-style tool metadata. +4. **Implementation functions** calling Vanta endpoints using utilities. +5. **Registry export** listing every tool/handler pair for automated registration. -### Step 4: Add to eval.ts +Example skeleton: ```typescript -// Import tools from barrel export +// 1. Imports import { - // ... existing tools - ListNewResourcesTool, - GetNewResourceTool, -} from "../operations/index.js"; - -// Add to tools array -const tools = [ - // ... existing tools - { - type: "function" as const, - function: { - name: ListNewResourcesTool.name, - description: ListNewResourcesTool.description, - parameters: zodToJsonSchema(ListNewResourcesTool.parameters), - }, - }, - // Add test cases... -]; -``` - -### Step 5: Update README.md - -Add the new operations to the main project README.md. - -## Best Practices - -### 1. Use DRY Utilities - -```typescript -// ✅ Good - Uses DRY utilities -export async function listControls( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/controls", args); -} - -// ❌ Bad - Manual implementation -export async function listControls( - args: z.infer, -): Promise { - const url = new URL("/v1/controls", baseApiUrl()); - if (args.pageSize) - url.searchParams.append("pageSize", args.pageSize.toString()); - // ... 20+ more lines of boilerplate -} -``` - -### 2. Use Schema Factories - -```typescript -// ✅ Good - Uses schema factory -const GetControlInput = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); + CallToolResult, + Tool, + z, + createConsolidatedSchema, + makeConsolidatedRequest, + buildUrl, + makeAuthenticatedRequest, + handleApiResponse, +} from "./common/imports.js"; -// ❌ Bad - Manual schema -const GetControlInput = z.object({ - controlId: z.string().describe("Control ID to retrieve, e.g. 'control-123'"), +// 2. Input Schemas +const ResourceInput = createConsolidatedSchema({ + paramName: "resourceId", + description: "Resource ID...", + resourceName: "resource", }); -``` - -### 3. Centralize Descriptions -```typescript -// ✅ Good - Uses centralized description -import { CONTROL_ID_DESCRIPTION } from "./common/imports.js"; -const schema = createIdSchema("controlId", CONTROL_ID_DESCRIPTION); - -// ❌ Bad - Hardcoded description -const schema = createIdSchema("controlId", "Control ID to retrieve"); -``` - -### 4. Consistent Error Handling - -```typescript -// ✅ Good - Uses standard response handling -const response = await makeAuthenticatedRequest(url); -return handleApiResponse(response); +const ResourceDetailsInput = z.object({ + resourceId: z.string().describe("Resource ID..."), + detailType: z.enum(["summary", "history"]), + ...createPaginationSchema().shape, +}); -// ❌ Bad - Manual error handling -if (!response.ok) { - return { content: [{ type: "text", text: `Error: ${response.statusText}` }] }; -} -return { - content: [{ type: "text", text: JSON.stringify(await response.json()) }], +// 3. Tool Definitions +export const ResourcesTool: Tool = { + name: "resources", + description: "Access resources...", + parameters: ResourceInput, }; -``` - -### 5. Type Safety - -```typescript -// ✅ Good - Explicit return type -export async function listControls( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/controls", args); -} -// ❌ Bad - Missing return type -export async function listControls(args: z.infer) { - return makePaginatedGetRequest("/v1/controls", args); -} -``` - -## Examples - -### Basic List Operation - -```typescript -const ListVendorsInput = createPaginationSchema(); - -export const ListVendorsTool: Tool = { - name: "list_vendors", - description: "List all vendors in your Vanta account.", - parameters: ListVendorsInput, +export const ResourceDetailsTool: Tool = { + name: "resource_details", + description: "Access resource details...", + parameters: ResourceDetailsInput, }; -export async function listVendors( - args: z.infer, +// 4. Implementation Functions +export async function resources( + args: z.infer, ): Promise { - return makePaginatedGetRequest("/v1/vendors", args); + return makeConsolidatedRequest("/v1/resources", args, "resourceId"); } -``` - -### Get by ID Operation - -```typescript -const GetVendorInput = createIdSchema("vendorId", VENDOR_ID_DESCRIPTION); -export const GetVendorTool: Tool = { - name: "get_vendor", - description: "Get vendor by ID.", - parameters: GetVendorInput, -}; - -export async function getVendor( - args: z.infer, +export async function resourceDetails( + args: z.infer, ): Promise { - return makeGetByIdRequest("vendors", args.vendorId); -} -``` - -### Custom Filtered List - -```typescript -const ListControlsInput = createPaginationSchema().extend({ - frameworkMatchesAny: z - .array(z.string()) - .describe("Framework IDs to filter by") - .optional(), -}); - -export async function listControls( - args: z.infer, -): Promise { - return makePaginatedGetRequest("/v1/controls", args); -} -``` - -### Nested Resource Operations - -```typescript -const ListVendorDocumentsInput = createIdWithPaginationSchema( - "vendorId", - VENDOR_ID_DESCRIPTION, -); - -export async function listVendorDocuments( - args: z.infer, -): Promise { - const { vendorId, ...params } = args; - const url = buildUrl(`/v1/vendors/${String(vendorId)}/documents`, params); + const { resourceId, detailType, ...params } = args; + const url = buildUrl( + `/v1/resources/${String(resourceId)}/${detailType}`, + params, + ); const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } -``` - -## Code Quality - -### ESLint Compliance - -- All operation files should pass ESLint with zero errors -- Use `npx eslint src/operations/*.ts --quiet` to check - -### Type Safety - -- All functions must have explicit return types -- Use proper TypeScript types throughout -- Avoid `any` types - -### Testing - -- Add evaluation test cases for all new tools in `eval.ts` -- Update `eval/README.md` with new test descriptions - -## Automated Tool Registry System - -### Overview - -The Vanta MCP Server uses an automated tool registry system that eliminates the need for manual tool registration in `index.ts`. - -### Key Benefits - -- **✅ Zero Maintenance**: Adding new tools requires no changes to `index.ts` -- **✅ Auto-Discovery**: New operations files are automatically detected and loaded -- **✅ Type Safety**: Full TypeScript support throughout the registration process -- **✅ Error Prevention**: No risk of forgetting to register new tools -- **✅ Scalability**: System grows effortlessly as you add more operations - -### How It Works - -1. **Registry Export**: Each operations file exports a `default` object with all its tools -2. **Auto-Discovery**: `src/registry.ts` imports all operations modules dynamically -3. **Automatic Registration**: `registerAllOperations()` registers each tool with the MCP server -4. **Single Call**: `index.ts` simply calls `await registerAllOperations(server)` -### Required Registry Export - -Every operations file MUST include this export at the end: - -```typescript -// Registry export for automated tool registration -export default { - tools: [ - { tool: ToolDefinition, handler: HandlerFunction }, - { tool: AnotherTool, handler: anotherHandler }, - // ... all tools in this file - ], -}; -``` - -**⚠️ Without this export, your tools will NOT be registered automatically!** - -### Adding New Tools - -To add a new tool to an existing operations file: - -1. Create your tool definition and handler function (following our patterns) -2. Add the tool entry to the `tools` array in the default export -3. The tool will be automatically registered on the next server restart - -Example: - -```typescript -export default { - tools: [ - { tool: ExistingTool, handler: existingHandler }, - { tool: NewTool, handler: newHandler }, // ← Just add here! - ], -}; -``` - -### Registry Implementation - -The automated registry system works through a simple pattern: - -**Operations File Pattern:** - -```typescript -// At the end of each operations file +// 5. Registry Export export default { tools: [ - { tool: ToolDefinition, handler: HandlerFunction }, - // ... all tools in this file + { tool: ResourcesTool, handler: resources }, + { tool: ResourceDetailsTool, handler: resourceDetails }, ], }; ``` -**Main Server Registration:** +## Naming and Tool Guidelines -```typescript -// index.ts -import { registerAllOperations } from "./registry.js"; +- **Tool names**: Use plural nouns for consolidated tools (e.g., `frameworks`, `documents`). +- **Schema constants**: Use PascalCase with `Input` suffix (e.g., `DocumentsInput`). +- **Implementation functions**: Use camelCase matching tool names (e.g., `frameworks`, `documentResources`). +- **Registry export**: Always include every tool/handler pair in the default export. +- **Descriptions**: Reference centralized descriptions from `common/descriptions.ts` whenever possible. -await registerAllOperations(server); -// ✅ Automatically registers all tools from all operations files -``` +## Automated Registration ---- +- Each operations file exports a default object `{ tools: [...] }`. +- `src/registry.ts` automatically imports every `src/operations/*.ts` module and registers the listed tools. +- Adding a new operation only requires exporting the tool and handler, then listing them in the default export. -### Common Files Organization +## Adding or Updating Operations -The operations directory uses a clean separation between individual operations and shared infrastructure: +1. **Create or edit input schemas** using factory helpers or explicit `z.object` definitions. +2. **Define or update tool metadata** with REST-aligned naming. +3. **Implement handlers** using `makeConsolidatedRequest`, `makePaginatedGetRequest`, or custom logic. +4. **Extend the default export** with the new tool/handler pair. +5. **Update `src/operations/index.ts`** to re-export the module (if a new file is added). +6. **Document new tools** in `README.md` (root) and update evaluation artifacts (below). -**Operations Files** (at root level): +## Evaluation Suite Updates -- Individual operation files (`controls.ts`, `vendors.ts`, `people.ts`, etc.) -- Each implements tools for a specific Vanta API resource -- Clean, focused implementation with consistent patterns +Whenever tools change: -**Common Infrastructure** (in `common/` subdirectory): +- Update `src/eval/eval.ts` to include the new tool definition and test cases. +- Update `src/eval/README.md` to describe new or renamed test scenarios. -- **`descriptions.ts`**: Centralized parameter descriptions for consistency -- **`imports.ts`**: Common imports barrel to reduce import boilerplate -- **`utils.ts`**: DRY utilities including schema factories and request handlers +## Testing and Validation -**Coordination Files**: +- **TypeScript Build**: `npm run build` +- **Linting**: `npm run lint -- src/operations/*.ts` +- **Manual Testing**: Invoke tools through the MCP interface if available. -- **`index.ts`**: Barrel export providing access to all operations from a single import -- **`README.md`**: Architecture documentation (this file) +## Quick Reference -This structure provides excellent visual separation between business logic (operations) and infrastructure (common utilities). +- **Consolidated tool example**: `frameworks.ts` (`frameworks` tool). +- **Nested resource example**: `documents.ts` (`document_resources` tool). +- **Download example**: `documents.ts` (`download_document_file` tool). +- **Common utilities**: `src/operations/common/utils.ts`. +- **Automated registry**: `src/registry.ts` + per-file `export default { tools: [...] }`. --- -This architecture provides a maintainable, consistent, and **highly scalable** foundation for extending the Vanta MCP Server with new operations while ensuring code quality and developer productivity. The automated registry system ensures that adding new functionality is effortless and error-free! +Use this README as the canonical reference for updates to the operations layer. Developers should rely on it when adding, modifying, or auditing tools. diff --git a/src/operations/common/descriptions.ts b/src/operations/common/descriptions.ts index ae23029..b9219dc 100644 --- a/src/operations/common/descriptions.ts +++ b/src/operations/common/descriptions.ts @@ -25,3 +25,6 @@ export const INTEGRATION_ID_DESCRIPTION = export const VENDOR_ID_DESCRIPTION = "Vendor ID to operate on, e.g. 'vendor-123' or specific vendor identifier"; + +export const DISCOVERED_VENDOR_ID_DESCRIPTION = + "Discovered vendor ID to operate on, e.g. 'discovered-vendor-123' or specific discovered vendor identifier"; diff --git a/src/operations/discovered-vendors.ts b/src/operations/discovered-vendors.ts index f6de368..f9797ee 100644 --- a/src/operations/discovered-vendors.ts +++ b/src/operations/discovered-vendors.ts @@ -9,6 +9,7 @@ import { buildUrl, makeAuthenticatedRequest, handleApiResponse, + DISCOVERED_VENDOR_ID_DESCRIPTION, } from "./common/imports.js"; // 2. Input Schemas @@ -16,8 +17,7 @@ const ListDiscoveredVendorsInput = createPaginationSchema(); const ListDiscoveredVendorAccountsInput = createIdWithPaginationSchema({ paramName: "discoveredVendorId", - description: - "Discovered vendor ID to get accounts for, e.g. 'discovered-vendor-123' or specific discovered vendor identifier", + description: DISCOVERED_VENDOR_ID_DESCRIPTION, }); // 3. Tool Definitions @@ -26,7 +26,7 @@ export const ListDiscoveredVendorsTool: Tool< > = { name: "list_discovered_vendors", description: - "List all discovered vendors in your Vanta account. Returns vendor IDs, names, and metadata for vendor risk management. Use this to see all vendors that have been discovered through automatic detection or manual entry.", + "List discovered vendors identified by Vanta's automated discovery. Returns vendor names, domains, discovery sources, and linkage status to managed vendor records.", parameters: ListDiscoveredVendorsInput, }; @@ -35,7 +35,7 @@ export const ListDiscoveredVendorAccountsTool: Tool< > = { name: "list_discovered_vendor_accounts", description: - "List a discovered vendor's accounts. Get all accounts associated with a specific discovered vendor for vendor risk management. Use this when you know a discovered vendor ID and want to see which accounts are linked to that vendor.", + "List accounts associated with a discovered vendor. Provide discoveredVendorId to retrieve account identifiers, connection details, and discovery metadata.", parameters: ListDiscoveredVendorAccountsInput, }; diff --git a/src/operations/documents.ts b/src/operations/documents.ts index b50e39d..beb780e 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -4,7 +4,7 @@ import { Tool, z, createConsolidatedSchema, - createIdWithPaginationSchema, + createPaginationSchema, makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, @@ -19,19 +19,14 @@ const DocumentsInput = createConsolidatedSchema({ resourceName: "document", }); -const ListDocumentControlsInput = createIdWithPaginationSchema({ - paramName: "documentId", - description: DOCUMENT_ID_DESCRIPTION, -}); - -const ListDocumentLinksInput = createIdWithPaginationSchema({ - paramName: "documentId", - description: DOCUMENT_ID_DESCRIPTION, -}); - -const ListDocumentUploadsInput = createIdWithPaginationSchema({ - paramName: "documentId", - description: DOCUMENT_ID_DESCRIPTION, +const DocumentResourcesInput = z.object({ + documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), + resourceType: z + .enum(["controls", "links", "uploads"]) + .describe( + "Type of document resource: 'controls' for associated controls, 'links' for external references, 'uploads' for attached files", + ), + ...createPaginationSchema().shape, }); const DownloadDocumentFileInput = z.object({ @@ -50,26 +45,11 @@ export const DocumentsTool: Tool = { parameters: DocumentsInput, }; -export const ListDocumentControlsTool: Tool = - { - name: "list_document_controls", - description: - "List document's controls. Get all security controls that are mapped to or associated with a specific document.", - parameters: ListDocumentControlsInput, - }; - -export const ListDocumentLinksTool: Tool = { - name: "list_document_links", - description: - "List document's links. Get all external links and references associated with a specific document.", - parameters: ListDocumentLinksInput, -}; - -export const ListDocumentUploadsTool: Tool = { - name: "list_document_uploads", +export const DocumentResourcesTool: Tool = { + name: "document_resources", description: - "List document's uploads. Get all files and uploads attached to a specific document for compliance documentation.", - parameters: ListDocumentUploadsInput, + "Access document-related resources including controls, links, and uploads. Specify resourceType to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached.", + parameters: DocumentResourcesInput, }; export const DownloadDocumentFileTool: Tool = @@ -87,29 +67,31 @@ export async function documents( return makeConsolidatedRequest("/v1/documents", args, "documentId"); } -export async function listDocumentControls( - args: z.infer, +export async function documentResources( + args: z.infer, ): Promise { - const { documentId, ...params } = args; - const url = buildUrl(`/v1/documents/${String(documentId)}/controls`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} + const { documentId, resourceType, ...params } = args; -export async function listDocumentLinks( - args: z.infer, -): Promise { - const { documentId, ...params } = args; - const url = buildUrl(`/v1/documents/${String(documentId)}/links`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} + const endpoints = { + controls: `/v1/documents/${String(documentId)}/controls`, + links: `/v1/documents/${String(documentId)}/links`, + uploads: `/v1/documents/${String(documentId)}/uploads`, + }; -export async function listDocumentUploads( - args: z.infer, -): Promise { - const { documentId, ...params } = args; - const url = buildUrl(`/v1/documents/${String(documentId)}/uploads`, params); + const endpoint = endpoints[resourceType]; + if (!endpoint) { + return { + content: [ + { + type: "text", + text: `Error: Invalid resourceType '${resourceType}'. Must be one of: controls, links, uploads`, + }, + ], + isError: true, + }; + } + + const url = buildUrl(endpoint, params); const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } @@ -184,9 +166,7 @@ Note: This is a binary file. Use appropriate tools to download and process the a export default { tools: [ { tool: DocumentsTool, handler: documents }, - { tool: ListDocumentControlsTool, handler: listDocumentControls }, - { tool: ListDocumentLinksTool, handler: listDocumentLinks }, - { tool: ListDocumentUploadsTool, handler: listDocumentUploads }, + { tool: DocumentResourcesTool, handler: documentResources }, { tool: DownloadDocumentFileTool, handler: downloadDocumentFile }, ], }; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index b96aabb..771cc4a 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -4,8 +4,8 @@ import { Tool, z, createConsolidatedSchema, - createIdWithPaginationSchema, makeConsolidatedRequest, + makePaginatedGetRequest, buildUrl, makeAuthenticatedRequest, handleApiResponse, @@ -19,27 +19,25 @@ const IntegrationsInput = createConsolidatedSchema({ resourceName: "integration", }); -const ListIntegrationResourceKindsInput = createIdWithPaginationSchema({ - paramName: "integrationId", - description: INTEGRATION_ID_DESCRIPTION, -}); - -const GetIntegrationResourceKindDetailsInput = z.object({ +const IntegrationResourcesInput = z.object({ integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - resourceKind: z - .string() + operation: z + .enum(["list_kinds", "get_kind_details", "list_resources", "get_resource"]) .describe( - "Resource kind to get details for, e.g. 'ec2-instances' or specific resource kind identifier", + "Integration resource operation: 'list_kinds' to get available resource types, 'get_kind_details' for schema information, 'list_resources' for all resources of a type, 'get_resource' for specific resource details", ), -}); - -const ListIntegrationResourcesInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), resourceKind: z .string() .describe( - "Resource kind to list resources for, e.g. 'ec2-instances' or specific resource kind identifier", - ), + "Resource kind to operate on, e.g. 'ec2-instances' or specific resource kind identifier (required for get_kind_details, list_resources, get_resource)", + ) + .optional(), + resourceId: z + .string() + .describe( + "Resource ID to retrieve, e.g. 'resource-123' or specific resource identifier (required for get_resource)", + ) + .optional(), pageSize: z .number() .min(1) @@ -52,20 +50,6 @@ const ListIntegrationResourcesInput = z.object({ .optional(), }); -const GetIntegrationResourceInput = z.object({ - integrationId: z.string().describe(INTEGRATION_ID_DESCRIPTION), - resourceKind: z - .string() - .describe( - "Resource kind the resource belongs to, e.g. 'ec2-instances' or specific resource kind identifier", - ), - resourceId: z - .string() - .describe( - "Resource ID to retrieve, e.g. 'resource-123' or specific resource identifier", - ), -}); - // 3. Tool Definitions export const IntegrationsTool: Tool = { name: "integrations", @@ -74,41 +58,13 @@ export const IntegrationsTool: Tool = { parameters: IntegrationsInput, }; -export const ListIntegrationResourceKindsTool: Tool< - typeof ListIntegrationResourceKindsInput -> = { - name: "list_integration_resource_kinds", - description: - "List integration's resource kinds. Get all resource types that are available through a specific integration. Use this to see what kinds of resources (EC2 instances, S3 buckets, etc.) can be monitored through an integration.", - parameters: ListIntegrationResourceKindsInput, -}; - -export const GetIntegrationResourceKindDetailsTool: Tool< - typeof GetIntegrationResourceKindDetailsInput -> = { - name: "get_integration_resource_kind_details", - description: - "Get integration resource kind details. Get detailed information about a specific resource kind within an integration. Use this to understand the schema and available fields for a particular resource type.", - parameters: GetIntegrationResourceKindDetailsInput, -}; - -export const ListIntegrationResourcesTool: Tool< - typeof ListIntegrationResourcesInput -> = { - name: "list_integration_resources", - description: - "List integration resources. Get all resources of a specific type within an integration. Use this to see all instances of a particular resource kind (like all EC2 instances) being monitored through an integration.", - parameters: ListIntegrationResourcesInput, -}; - -export const GetIntegrationResourceTool: Tool< - typeof GetIntegrationResourceInput -> = { - name: "get_integration_resource", - description: - "Get integration resource by ID. Get detailed information about a specific resource within an integration. Use this to see the current state and attributes of a particular monitored resource.", - parameters: GetIntegrationResourceInput, -}; +export const IntegrationResourcesTool: Tool = + { + name: "integration_resources", + description: + "Access integration resources including resource kinds, resource kind details, and specific resources. Specify operation to perform: 'list_kinds' for available resource types, 'get_kind_details' for schema information, 'list_resources' for all resources of a type, or 'get_resource' for specific resource details.", + parameters: IntegrationResourcesInput, + }; // 4. Implementation Functions export async function integrations( @@ -117,63 +73,94 @@ export async function integrations( return makeConsolidatedRequest("/v1/integrations", args, "integrationId"); } -export async function listIntegrationResourceKinds( - args: z.infer, -): Promise { - const { integrationId, ...params } = args; - const url = buildUrl( - `/v1/integrations/${String(integrationId)}/resource-kinds`, - params, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function getIntegrationResourceKindDetails( - args: z.infer, -): Promise { - const url = buildUrl( - `/v1/integrations/${String(args.integrationId)}/resource-kinds/${String(args.resourceKind)}`, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listIntegrationResources( - args: z.infer, -): Promise { - const { integrationId, resourceKind, ...params } = args; - const url = buildUrl( - `/v1/integrations/${String(integrationId)}/resource-kinds/${String(resourceKind)}/resources`, - params, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function getIntegrationResource( - args: z.infer, +export async function integrationResources( + args: z.infer, ): Promise { - const url = buildUrl( - `/v1/integrations/${String(args.integrationId)}/resource-kinds/${String(args.resourceKind)}/resources/${String(args.resourceId)}`, - ); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); + const { integrationId, operation, resourceKind, resourceId, ...params } = + args; + + switch (operation) { + case "list_kinds": { + return makePaginatedGetRequest( + `/v1/integrations/${String(integrationId)}/resource-kinds`, + params, + ); + } + + case "get_kind_details": { + if (!resourceKind) { + return { + content: [ + { + type: "text", + text: "Error: resourceKind is required for get_kind_details operation", + }, + ], + isError: true, + }; + } + const kindUrl = buildUrl( + `/v1/integrations/${String(integrationId)}/resource-kinds/${String(resourceKind)}`, + ); + const kindResponse = await makeAuthenticatedRequest(kindUrl); + return handleApiResponse(kindResponse); + } + + case "list_resources": { + if (!resourceKind) { + return { + content: [ + { + type: "text", + text: "Error: resourceKind is required for list_resources operation", + }, + ], + isError: true, + }; + } + return makePaginatedGetRequest( + `/v1/integrations/${String(integrationId)}/resource-kinds/${String(resourceKind)}/resources`, + params, + ); + } + + case "get_resource": { + if (!resourceKind || !resourceId) { + return { + content: [ + { + type: "text", + text: "Error: both resourceKind and resourceId are required for get_resource operation", + }, + ], + isError: true, + }; + } + const resourceUrl = buildUrl( + `/v1/integrations/${String(integrationId)}/resource-kinds/${String(resourceKind)}/resources/${String(resourceId)}`, + ); + const resourceResponse = await makeAuthenticatedRequest(resourceUrl); + return handleApiResponse(resourceResponse); + } + + default: { + return { + content: [ + { + type: "text", + text: `Error: Invalid operation '${operation as string}'. Must be one of: list_kinds, get_kind_details, list_resources, get_resource`, + }, + ], + isError: true, + }; + } + } } // Registry export for automated tool registration export default { tools: [ { tool: IntegrationsTool, handler: integrations }, - { - tool: ListIntegrationResourceKindsTool, - handler: listIntegrationResourceKinds, - }, - { - tool: GetIntegrationResourceKindDetailsTool, - handler: getIntegrationResourceKindDetails, - }, - { tool: ListIntegrationResourcesTool, handler: listIntegrationResources }, - { tool: GetIntegrationResourceTool, handler: getIntegrationResource }, + { tool: IntegrationResourcesTool, handler: integrationResources }, ], }; diff --git a/src/operations/vendors.ts b/src/operations/vendors.ts index 6afc2dd..b91bf2a 100644 --- a/src/operations/vendors.ts +++ b/src/operations/vendors.ts @@ -4,7 +4,6 @@ import { Tool, z, createConsolidatedSchema, - createIdWithPaginationSchema, makeConsolidatedRequest, buildUrl, makeAuthenticatedRequest, @@ -19,19 +18,23 @@ const VendorsInput = createConsolidatedSchema({ resourceName: "vendor", }); -const ListVendorDocumentsInput = createIdWithPaginationSchema({ - paramName: "vendorId", - description: VENDOR_ID_DESCRIPTION, -}); - -const ListVendorFindingsInput = createIdWithPaginationSchema({ - paramName: "vendorId", - description: VENDOR_ID_DESCRIPTION, -}); - -const ListVendorSecurityReviewsInput = createIdWithPaginationSchema({ - paramName: "vendorId", - description: VENDOR_ID_DESCRIPTION, +const VendorComplianceInput = z.object({ + vendorId: z.string().describe(VENDOR_ID_DESCRIPTION), + complianceType: z + .enum(["documents", "findings", "security_reviews"]) + .describe( + "Type of vendor compliance data: 'documents' for compliance documentation, 'findings' for security findings, 'security_reviews' for security assessments", + ), + pageSize: z + .number() + .min(1) + .max(100) + .describe("Number of items to return per page (1-100)") + .optional(), + pageCursor: z + .string() + .describe("Cursor for pagination to get the next page of results") + .optional(), }); const GetVendorSecurityReviewInput = z.object({ @@ -70,27 +73,11 @@ export const VendorsTool: Tool = { parameters: VendorsInput, }; -export const ListVendorDocumentsTool: Tool = { - name: "list_vendor_documents", - description: - "List vendor's documents. Get all documents associated with a specific vendor for compliance and risk assessment.", - parameters: ListVendorDocumentsInput, -}; - -export const ListVendorFindingsTool: Tool = { - name: "list_vendor_findings", +export const VendorComplianceTool: Tool = { + name: "vendor_compliance", description: - "List vendor's findings. Get all security findings and compliance issues identified for a specific vendor.", - parameters: ListVendorFindingsInput, -}; - -export const ListVendorSecurityReviewsTool: Tool< - typeof ListVendorSecurityReviewsInput -> = { - name: "list_vendor_security_reviews", - description: - "List vendor's security reviews. Get all security assessments and reviews conducted for a specific vendor.", - parameters: ListVendorSecurityReviewsInput, + "Access vendor compliance data including documents, findings, and security reviews. Specify complianceType to get the specific type of compliance information for a vendor. Use this to explore vendor compliance documentation, security findings, and assessment history.", + parameters: VendorComplianceInput, }; export const GetVendorSecurityReviewTool: Tool< @@ -118,32 +105,31 @@ export async function vendors( return makeConsolidatedRequest("/v1/vendors", args, "vendorId"); } -export async function listVendorDocuments( - args: z.infer, +export async function vendorCompliance( + args: z.infer, ): Promise { - const { vendorId, ...params } = args; - const url = buildUrl(`/v1/vendors/${String(vendorId)}/documents`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listVendorFindings( - args: z.infer, -): Promise { - const { vendorId, ...params } = args; - const url = buildUrl(`/v1/vendors/${String(vendorId)}/findings`, params); - const response = await makeAuthenticatedRequest(url); - return handleApiResponse(response); -} - -export async function listVendorSecurityReviews( - args: z.infer, -): Promise { - const { vendorId, ...params } = args; - const url = buildUrl( - `/v1/vendors/${String(vendorId)}/security-reviews`, - params, - ); + const { vendorId, complianceType, ...params } = args; + + const endpoints = { + documents: `/v1/vendors/${String(vendorId)}/documents`, + findings: `/v1/vendors/${String(vendorId)}/findings`, + security_reviews: `/v1/vendors/${String(vendorId)}/security-reviews`, + }; + + const endpoint = endpoints[complianceType]; + if (!endpoint) { + return { + content: [ + { + type: "text", + text: `Error: Invalid complianceType '${complianceType}'. Must be one of: documents, findings, security_reviews`, + }, + ], + isError: true, + }; + } + + const url = buildUrl(endpoint, params); const response = await makeAuthenticatedRequest(url); return handleApiResponse(response); } @@ -174,9 +160,7 @@ export async function listVendorSecurityReviewDocuments( export default { tools: [ { tool: VendorsTool, handler: vendors }, - { tool: ListVendorDocumentsTool, handler: listVendorDocuments }, - { tool: ListVendorFindingsTool, handler: listVendorFindings }, - { tool: ListVendorSecurityReviewsTool, handler: listVendorSecurityReviews }, + { tool: VendorComplianceTool, handler: vendorCompliance }, { tool: GetVendorSecurityReviewTool, handler: getVendorSecurityReview }, { tool: ListVendorSecurityReviewDocumentsTool, From 0d7dd07ef7d5fa231d995bca26a7b4a1ba5cfa98 Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Fri, 3 Oct 2025 16:37:07 -0400 Subject: [PATCH 23/24] Config file added to control which specific tools are enabled --- README.md | 344 ++++++++------------------------------- src/config.ts | 36 ++++ src/index.ts | 8 + src/operations/README.md | 4 +- src/registry.ts | 43 ++++- 5 files changed, 155 insertions(+), 280 deletions(-) create mode 100644 src/config.ts diff --git a/README.md b/README.md index 545f8dc..19d9fde 100644 --- a/README.md +++ b/README.md @@ -8,231 +8,79 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid ### Controls -- List all security controls across all frameworks in your Vanta account -- View control names, descriptions, framework mappings, and implementation status -- Get specific tests that validate each security control -- Access pre-built controls from Vanta's control library -- View documents providing evidence for specific security controls -- Understand which automated tests monitor compliance for specific controls - -| Tool Name | Description | -| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. | -| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Returns test details, current status, and any failing entities for the control's tests. | -| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. | -| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. | -| [`controls`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. | - -### Discovered Vendors - -- Identify unmanaged vendors detected by Vanta's discovery engine -- Review automatically discovered vendor profiles before they are confirmed as managed vendors -- Inspect accounts associated with a discovered vendor to understand potential risk exposure - -| Tool Name | Description | -| ------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors identified by Vanta's automated discovery. Returns vendor names, domains, discovery sources, and linkage status to managed vendor records. | -| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List accounts associated with a discovered vendor. Provide discoveredVendorId to retrieve account identifiers, connection details, and discovery metadata. | +- List security controls or fetch a specific control by ID +- Discover which automated tests validate each control +- Review evidence documents mapped to controls + +| Tool Name | Description | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [`controls`](https://developer.vanta.com/reference/listcontrols) | Access security controls in your Vanta account. Provide controlId to get a specific control, or omit to list all controls with optional framework filtering. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Enumerate automated tests that validate a specific security control, including status and failing entity details. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List documents that provide evidence for a specific security control so you can quickly locate supporting artifacts. | ### Documents -- List all documents in your Vanta account for compliance and evidence management -- Get detailed information about specific documents including metadata and compliance mappings -- Access document-related resources including controls, links, and uploads through intelligent consolidation -- Intelligently download file uploads with automatic MIME type handling - text files return readable content, binary files return metadata +- Enumerate compliance documents across your organization +- Inspect the controls, links, or uploads associated with a document -| Tool Name | Description | -| ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`documents`](https://developer.vanta.com/reference/listdocuments) | Access documents in your Vanta account. Provide documentId to get a specific document, or omit to list all documents. Returns document IDs, names, types, and metadata for compliance and evidence management. | -| [`document_resources`](https://developer.vanta.com/reference/listdocumentcontrols) | Access document-related resources including controls, links, and uploads. Specify resourceType ('controls', 'links', 'uploads') to get the specific type of resource associated with a document. | -| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download document file by upload ID. Get the actual uploaded document file. Intelligently handles different MIME types: returns text content for readable files, metadata information for binary files. | +| Tool Name | Description | +| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | +| [`documents`](https://developer.vanta.com/reference/listdocuments) | List documents in your Vanta account or retrieve a specific document by ID with metadata for compliance and evidence management. | +| [`document_resources`](https://developer.vanta.com/reference/listdocumentcontrols) | Retrieve resources linked to a document (controls, links, uploads) by specifying the desired resource type. | ### Frameworks -- List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, etc.) -- View completion status and progress metrics for each framework -- Get detailed security control requirements for specific compliance frameworks -- Access implementation guidance and current compliance status for framework controls - -| Tool Name | Description | -| ---------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. | -| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. | -| [`frameworks`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. | - -### Groups - -- List all organizational groups for structure and access management -- Get detailed group information including member counts and access permissions -- View group membership to understand who has group-based access permissions +- Review framework adoption and progress metrics across your organization +- Drill into the controls required by each framework -| Tool Name | Description | -| ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -| [`groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. | -| [`groups`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. | -| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. | +| Tool Name | Description | +| ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List compliance frameworks available in your Vanta account along with completion status and progress metrics. | +| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Retrieve the controls associated with a framework, including descriptions, implementation guidance, and current compliance status. | ### Integrations -- List all connected integrations in your Vanta account (AWS, Azure, GCP, Snyk, etc.) -- Get detailed information about specific integrations and their configurations -- Access integration resources including resource kinds, resource details, and specific resources through intelligent consolidation -- Monitor which integrations are actively connected to your instance +- Enumerate connected integrations and review their metadata +- Explore supported resource kinds and fetch integration resources on demand -| Tool Name | Description | -| ------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`integrations`](https://developer.vanta.com/reference/listintegrations) | Access connected integrations in your Vanta account. Provide integrationId to get a specific integration, or omit to list all integrations. Returns integration details, supported resource kinds, and connection status for compliance monitoring. | -| [`integration_resources`](https://developer.vanta.com/reference/listresourcekindsummaries) | Access integration resources including resource kinds, resource kind details, and specific resources. Specify operation ('list_kinds', 'get_kind_details', 'list_resources', 'get_resource') to perform the desired action. | - -### Monitored Computers - -- Monitor all computers across your organization for compliance and security -- Access detailed computer information including hostnames, operating systems, and security status -- Manage endpoint security and compliance across diverse computing environments - -| Tool Name | Description | -| ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. | -| [`monitored_computers`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List integrations connected to your Vanta account or fetch details for a specific integration, including supported resource kinds and connection status. | +| [`integration_resources`](https://developer.vanta.com/reference/listresourcekindsummaries) | Access integration resources by selecting the desired operation (`list_kinds`, `get_kind_details`, `list_resources`, or `get_resource`). | ### People -- List all people in your organization for compliance and security management -- Access detailed person information including roles, email addresses, and group memberships -- Manage organizational structure and access control through comprehensive people data - -| Tool Name | Description | -| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. | -| [`people`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. | +- List or retrieve people for compliance and access reviews -### Policies - -- List all policies in your Vanta account for compliance and governance management -- Get detailed policy information including content, approval status, and compliance mappings -- Access organizational policies for security, privacy, and operational governance -- View policy metadata including names, types, and associated compliance frameworks - -| Tool Name | Description | -| ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | -| [`policies`](https://developer.vanta.com/reference/listpolicies) | List all policies in your Vanta account. Returns policy IDs, names, types, and metadata for compliance and governance management. | -| [`policies`](https://developer.vanta.com/reference/getpolicy) | Get policy by ID. Retrieve detailed information about a specific policy when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | +| [`people`](https://developer.vanta.com/reference/listpeople) | List people in your Vanta account or retrieve a specific person by ID, including role, email, and group membership metadata. | ### Risks -- Get all the risk scenarios you are managing in your current risk register -- Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more -- Filterable by risk category (Access Control, Cryptography, Privacy, and many others) +- Track risk scenarios, their status, scoring, and treatment plans -| Tool Name | Description | -| ------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. | -| [`risks`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------ | +| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | List risk scenarios managed in your risk register or fetch a specific scenario by ID to review status, scoring, and treatment information. | ### Tests -- Access Vanta's 1,200+ automated security tests that run continuously to monitor compliance -- Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration, or compliance framework -- Get specific resources (entities) that are failing particular security tests -- Essential for understanding exactly which infrastructure components need remediation - -| Tool Name | Description | -| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status, cloud integration, or compliance framework. Returns test results showing which security controls are passing or failing. | -| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. Essential for understanding exactly which infrastructure components need remediation. | -| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the list_tests response or from the address bar of your browser. | - -### Trust Centers - -- Access complete Trust Center configuration, branding, and public visibility settings -- Manage Trust Center access requests from potential customers and stakeholders -- Track detailed viewer activity and engagement analytics across Trust Center content -- Organize and manage control categories for clear compliance presentation -- Publish and manage compliance controls with implementation details and evidence -- Maintain comprehensive FAQ sections for customer transparency and communication -- Provide downloadable resources including compliance documents and certifications -- Enable customer self-service access to compliance and security information - -| Tool Name | Description | -| ------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. | -| [`trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. | -| [`trust_center_access_requests`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. | -| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. | -| [`trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. | -| [`trust_center_control_categories`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. | -| [`trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. | -| [`trust_center_controls`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. | -| [`trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. | -| [`trust_center_faqs`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. | -| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. | -| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. | -| [`get_trust_center_resource_media`](https://developer.vanta.com/reference/gettrustcenterresourcemedia) | Download Trust Center document media. Get the actual uploaded document/media file for a Trust Center resource for review or audit purposes. | -| [`trust_center_subprocessors`](https://developer.vanta.com/reference/listtrustcentersubprocessors) | List Trust Center subprocessors. Get all subprocessors displayed in a specific Trust Center for third-party service provider transparency. | -| [`trust_center_subprocessors`](https://developer.vanta.com/reference/gettrustcentersubprocessor) | Get Trust Center subprocessor by ID. Retrieve detailed information about a specific subprocessor including compliance details and certifications. | -| [`trust_center_updates`](https://developer.vanta.com/reference/listtrustcenterupdates) | List Trust Center updates. Get all updates and announcements published in a specific Trust Center for compliance status changes and notifications. | -| [`trust_center_updates`](https://developer.vanta.com/reference/gettrustcenterupdate) | Get Trust Center update by ID. Retrieve detailed information about a specific update including content, publication date, and compliance impact. | -| [`trust_center_viewers`](https://developer.vanta.com/reference/listtrustcenterviewers) | List Trust Center viewers. Get all users who have access to view a specific Trust Center for access management and audit purposes. | -| [`trust_center_viewers`](https://developer.vanta.com/reference/gettrustcenterviewer) | Get Trust Center viewer by ID. Retrieve detailed information about a specific viewer including access permissions and activity history. | -| [`get_trust_center_subscriber`](https://developer.vanta.com/reference/gettrustcentersubscriber) | Get Trust Center subscriber by ID. Retrieve detailed information about a specific subscriber including subscription preferences and notification settings. | -| [`trust_center_subscriber_groups`](https://developer.vanta.com/reference/gettrustcentersubscribergroup) | Get Trust Center subscriber group by ID. Retrieve detailed information about a specific subscriber group including members and notification preferences. | -| [`trust_center_subscriber_groups`](https://developer.vanta.com/reference/listtrustcentersubscribergroups) | List Trust Center subscriber groups. Get all subscriber groups configured for a specific Trust Center for notification group management. | -| [`list_trust_center_historical_access_requests`](https://developer.vanta.com/reference/listtrustcenterhistoricalaccessrequests) | List Trust Center historical access requests. Get all past access requests for a specific Trust Center for audit and compliance tracking. | -| [`list_trust_center_subscribers`](https://developer.vanta.com/reference/listtrustcentersubscribers) | List Trust Center subscribers. Get all subscribers to a specific Trust Center for update notifications and communication management. | - -### Vendor Risk Attributes - -- Understand available vendor risk attributes for comprehensive risk assessment -- Categorize and evaluate vendor risks using standardized risk assessment criteria -- Access risk attribute IDs, names, categories, and assessment criteria for vendor risk management - -| Tool Name | Description | -| ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. | - -### Vendors - -- List all vendors in your Vanta account for vendor risk management -- Get detailed vendor information including contact details and website URLs -- Access vendor compliance data including documents, findings, and security reviews through intelligent consolidation -- Manage vendor relationships and due diligence tracking -- Review history of security assessments and due diligence activities through consolidated access - -| Tool Name | Description | -| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`vendors`](https://developer.vanta.com/reference/listvendors) | Access vendors in your Vanta account. Provide vendorId to get a specific vendor, or omit to list all vendors. Returns vendor details, risk levels, and management status for third-party risk assessment. | -| [`vendor_compliance`](https://developer.vanta.com/reference/listvendordocuments) | Access vendor compliance data including documents, findings, and security reviews. Specify complianceType ('documents', 'findings', 'security_reviews') to get the specific type of compliance information for a vendor. | -| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get vendor security review by ID. Retrieve detailed information about a specific security review for a vendor. | -| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | List vendor security review's documents. Get all documents associated with a specific vendor security review. | - -### Vulnerabilities - -- Monitor all vulnerabilities detected across your infrastructure and applications -- Access detailed vulnerability information including CVE data, severity levels, and affected assets - -| Tool Name | Description | -| ------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. | -| [`vulnerabilities`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. | - -### Vulnerability Remediations +- Monitor automated security tests running in your environment +- Investigate the entities associated with a specific test -- Track vulnerability remediation efforts and timelines for security management -- Ensure timely resolution of security issues through comprehensive remediation tracking +| Tool Name | Description | +| ----------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status, integration, or framework to understand which controls are passing or failing. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get the resources monitored by a specific security test, including failing entities that require remediation. | -| Tool Name | Description | -| -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. | - -### Vulnerable Assets +### Vulnerabilities -- Identify vulnerable assets and understand their security status -- Prioritize security efforts based on asset vulnerability associations and risk levels +- Review vulnerabilities surfaced by Vanta, including CVE metadata and affected assets -| Tool Name | Description | -| --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| [`vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. | -| [`vulnerable_assets`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. | +| Tool Name | Description | +| ------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | List vulnerabilities detected across your infrastructure or retrieve a specific vulnerability by ID with CVE details, severity, and impacted asset information. | ### Multi-Region Support @@ -241,58 +89,22 @@ A [Model Context Protocol](https://modelcontextprotocol.com/) server that provid ## Tools -| Tool Name | Description | -| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`list_tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status (OK, NEEDS_ATTENTION, DEACTIVATED), cloud integration (aws, azure, gcp), or compliance framework (soc2, iso27001, hipaa). Returns test results showing which security controls are passing or failing across your infrastructure. | -| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get specific resources (entities) that are failing a particular security test. For example, if an AWS security group test is failing, this returns the actual security group IDs and details about what's wrong. Essential for understanding exactly which infrastructure components need remediation. | -| [`get_test`](https://developer.vanta.com/reference/gettest) | Get the details of a specific test by its ID. The ID of a test may be retrieved from the `list_tests` response or from the address bar of your browser after /tests/. | -| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List all compliance frameworks available in your Vanta account (SOC 2, ISO 27001, HIPAA, GDPR, FedRAMP, PCI, etc.) along with completion status and progress metrics. Shows which frameworks you're actively pursuing and their current compliance state. | -| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Get detailed security control requirements for a specific compliance framework. Returns the specific controls, their descriptions, implementation guidance, and current compliance status. Essential for understanding what security measures are required for each compliance standard. | -| [`frameworks`](https://developer.vanta.com/reference/getframework) | Get framework by ID. Retrieve detailed information about a specific compliance framework when its ID is known. The ID of a framework can be found from frameworks response. Returns complete framework details including name, description, completion status, progress metrics, and compliance state. | -| [`controls`](https://developer.vanta.com/reference/listcontrols) | List all security controls across all frameworks in your Vanta account. Returns control names, descriptions, framework mappings, and current implementation status. Use this to see all available controls or to find a specific control ID for use with other tools. | -| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Get all automated tests that validate a specific security control. Use this when you know a control ID and want to see which specific tests monitor compliance for that control. Returns test details, current status, and any failing entities for the control's tests. | -| [`list_library_controls`](https://developer.vanta.com/reference/listlibrarycontrols) | List Vanta controls from the library. These are pre-built security controls available in Vanta's control library that can be added to your account. Different from controls which lists controls already in your account - this shows available controls you can implement. | -| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List a control's documents. Get all documents that are associated with or provide evidence for a specific security control. Use this when you know a control ID and want to see which documents are mapped to that control for compliance evidence. | -| [`controls`](https://developer.vanta.com/reference/getcontrol) | Get control by an ID. Retrieve detailed information about a specific security control when its ID is known. The ID of a control can be found from controls or list_framework_controls responses. Returns complete control details including name, description, framework mappings, and implementation status. | -| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | Get all the risk scenarios you are managing in your current risk register. Returns details about each risk scenario's status, inherent & residual risk score, treatment plan, and more. Filterable by risk category (Access Control, Cryptography, Privacy, and many others). | -| [`risks`](https://developer.vanta.com/reference/getriskscenario) | Get risk scenario by ID. Retrieve detailed information about a specific risk scenario when its ID is known. The ID of a risk scenario can be found from risks response. Returns complete risk details including status, inherent & residual risk scores, treatment plan, and more. | -| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List all connected integrations in your Vanta account. Returns integration id, display name, resource kinds supported by the integration, and how many connections exist for such integration. Use this to see all integrations connected in your Vanta instance. | -| [`integrations`](https://developer.vanta.com/reference/getintegration) | Get integration by ID. Retrieve detailed information about a specific integration when its ID is known. The ID of an integration can be found from integrations response. Returns complete integration details including configuration, resource kinds, and connection status. | -| [`integration_resources`](https://developer.vanta.com/reference/listresourcekindsummaries) | Access integration resources including resource kinds, resource kind details, and specific resources. Specify operation ('list_kinds', 'get_kind_details', 'list_resources', 'get_resource') to perform the desired action. Use this to explore what resources an integration can monitor and access detailed resource information. | -| [`vendor_compliance`](https://developer.vanta.com/reference/listvendordocuments) | Access vendor compliance data including documents, findings, and security reviews. Specify complianceType ('documents', 'findings', 'security_reviews') to get the specific type of compliance information for a vendor. Use this to explore vendor compliance documentation, security findings, and assessment history. | -| [`get_vendor_security_review`](https://developer.vanta.com/reference/getsecurityreviewsbyid) | Get vendor security review by ID. Retrieve detailed information about a specific security review for a vendor. Use this to get complete details about a particular security assessment including findings, status, and recommendations. | -| [`list_vendor_security_review_documents`](https://developer.vanta.com/reference/getsecurityreviewdocuments) | List vendor security review's documents. Get all documents associated with a specific vendor security review. Use this to access supporting documentation, evidence, and reports related to a security assessment. | -| [`documents`](https://developer.vanta.com/reference/listdocuments) | Access documents in your Vanta account. Provide documentId to get a specific document, or omit to list all documents. Returns document IDs, names, types, and metadata for compliance and evidence management. Use this to see all documents available for compliance frameworks and controls. | -| [`document_resources`](https://developer.vanta.com/reference/listdocumentcontrols) | Access document-related resources including controls, links, and uploads. Specify resourceType ('controls', 'links', 'uploads') to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached. | -| [`download_document_file`](https://developer.vanta.com/reference/getdocumentupload) | Download document file by upload ID. Get the actual uploaded document file. Intelligently handles different MIME types: returns text content for readable files, metadata information for binary files. Use this to access compliance evidence and documentation content that can be analyzed. | -| [`policies`](https://developer.vanta.com/reference/listpolicies) | Access policies in your Vanta account. Provide policyId to get a specific policy, or omit to list all policies. Returns policy IDs, names, and metadata for compliance and governance management. Use this to see all policies available for compliance frameworks and organizational governance. | -| [`list_discovered_vendors`](https://developer.vanta.com/reference/listdiscoveredvendors) | List discovered vendors identified by Vanta's automated discovery. Returns vendor names, domains, discovery sources, and linkage status to managed vendor records. | -| [`list_discovered_vendor_accounts`](https://developer.vanta.com/reference/listdiscoveredvendoraccounts) | List accounts associated with a discovered vendor. Provide discoveredVendorId to retrieve account identifiers, connection details, and discovery metadata. | -| [`groups`](https://developer.vanta.com/reference/listgroups) | List all groups in your Vanta account. Returns group IDs, names, descriptions, and metadata for organizational structure and access management. Use this to see all groups available for people assignment and access control. | -| [`groups`](https://developer.vanta.com/reference/getgroup) | Get group by ID. Retrieve detailed information about a specific group when its ID is known. The ID of a group can be found from groups response. Returns complete group details including name, description, member count, and access permissions. | -| [`list_group_people`](https://developer.vanta.com/reference/listgrouppeople) | List people in a group. Get all people who are members of a specific group for organizational structure and access management. Use this to understand group membership and review who has group-based access permissions. | -| [`people`](https://developer.vanta.com/reference/listpeople) | List all people in your Vanta account. Returns person IDs, names, email addresses, and metadata for organizational structure and access management. Use this to see all people in your organization for compliance and security management. | -| [`people`](https://developer.vanta.com/reference/getperson) | Get person by ID. Retrieve detailed information about a specific person when their ID is known. The ID of a person can be found from people response. Returns complete person details including name, email, role, group memberships, and access permissions. | -| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | Get vulnerabilities in your Vanta account. Returns vulnerability IDs, CVE information, severity levels, and affected assets for security monitoring and remediation. Use this to see all vulnerabilities detected across your infrastructure and applications. | -| [`vulnerabilities`](https://developer.vanta.com/reference/getvulnerability) | Get vulnerability by ID. Retrieve detailed information about a specific vulnerability when its ID is known. The ID of a vulnerability can be found from vulnerabilities response. Returns complete vulnerability details including CVE information, severity, affected assets, and remediation status. | -| [`list_vulnerability_remediations`](https://developer.vanta.com/reference/listvulnerabilityremediations) | List vulnerability remediations in your Vanta account. Returns remediation IDs, associated vulnerabilities, remediation status, and timeline information for security management. Use this to track vulnerability remediation efforts and ensure timely resolution of security issues. | -| [`vulnerable_assets`](https://developer.vanta.com/reference/listvulnerableassets) | List assets associated with vulnerabilities in your Vanta account. Returns asset IDs, vulnerability associations, asset types, and security status for infrastructure security management. Use this to identify which assets are affected by vulnerabilities and prioritize security efforts. | -| [`vulnerable_assets`](https://developer.vanta.com/reference/getvulnerableasset) | Get vulnerable asset by ID. Retrieve detailed information about a specific vulnerable asset when its ID is known. The ID of a vulnerable asset can be found from vulnerable_assets response. Returns complete asset details including vulnerability associations, asset type, and security status. | -| [`monitored_computers`](https://developer.vanta.com/reference/listmonitoredcomputers) | List monitored computers in your Vanta account. Returns computer IDs, hostnames, operating systems, and security status for endpoint security management. Use this to see all computers being monitored for compliance and security across your organization. | -| [`monitored_computers`](https://developer.vanta.com/reference/getmonitoredcomputer) | Get monitored computer by ID. Retrieve detailed information about a specific monitored computer when its ID is known. The ID of a computer can be found from monitored_computers response. Returns complete computer details including hostname, OS, security status, and compliance information. | -| [`list_vendor_risk_attributes`](https://developer.vanta.com/reference/listvenderriskattributes) | List vendor risk attributes in your Vanta account. Returns risk attribute IDs, names, categories, and assessment criteria for vendor risk management. Use this to understand the available risk attributes for evaluating and categorizing vendor risks across your organization. | -| [`get_trust_center`](https://developer.vanta.com/reference/gettrustcenter) | Get Trust Center information. Retrieve detailed information about a specific Trust Center including configuration, branding, and public visibility settings. Use this to access Trust Center details for compliance transparency and customer communication. | -| [`trust_center_access_requests`](https://developer.vanta.com/reference/listtrustcenteraccessrequests) | List Trust Center access requests. Get all pending and processed access requests for a specific Trust Center. Use this to manage and review who is requesting access to your Trust Center content and compliance information. | -| [`trust_center_access_requests`](https://developer.vanta.com/reference/gettrustcenteraccessrequest) | Get Trust Center access request by ID. Retrieve detailed information about a specific access request including requester details, status, and request metadata. Use this to review individual access requests for approval or denial decisions. | -| [`list_trust_center_viewer_activity_events`](https://developer.vanta.com/reference/listtrustcentervieweractivityevents) | List Trust Center viewer activity events. Get all viewer activity and engagement events for a specific Trust Center including page views, document downloads, and user interactions. Use this to track Trust Center usage and engagement analytics. | -| [`trust_center_control_categories`](https://developer.vanta.com/reference/listtrustcentercontrolcategories) | List Trust Center control categories. Get all control categories configured for a specific Trust Center including category names, descriptions, and organization. Use this to understand how compliance controls are categorized and presented to Trust Center visitors. | -| [`trust_center_control_categories`](https://developer.vanta.com/reference/gettrustcentercontrolcategory) | Get Trust Center control category by ID. Retrieve detailed information about a specific control category including its configuration, associated controls, and display settings. Use this to access specific control category details for Trust Center management. | -| [`trust_center_controls`](https://developer.vanta.com/reference/listtrustcentercontrols) | List Trust Center controls. Get all compliance controls published in a specific Trust Center including control descriptions, implementation status, and evidence. Use this to see which controls are publicly visible to Trust Center visitors. | -| [`trust_center_controls`](https://developer.vanta.com/reference/gettrustcentercontrol) | Get Trust Center control by ID. Retrieve detailed information about a specific control published in the Trust Center including implementation details, evidence, and compliance status. Use this to access individual control information for Trust Center transparency. | -| [`trust_center_faqs`](https://developer.vanta.com/reference/listtrustcenterfaqs) | List Trust Center FAQs. Get all frequently asked questions configured for a specific Trust Center including questions, answers, and organization. Use this to see what information is provided to Trust Center visitors through the FAQ section. | -| [`trust_center_faqs`](https://developer.vanta.com/reference/gettrustcenterfaq) | Get Trust Center FAQ by ID. Retrieve detailed information about a specific FAQ including the question, answer, and display settings. Use this to access individual FAQ content for Trust Center management and customer communication. | -| [`list_trust_center_resources`](https://developer.vanta.com/reference/listtrustcenterresources) | List Trust Center resources. Get all resources and documents available in a specific Trust Center including compliance documents, certifications, and downloadable materials. Use this to see what resources are publicly available to Trust Center visitors. | -| [`get_trust_center_document`](https://developer.vanta.com/reference/gettrustcenterdocument) | Get Trust Center document by ID. Retrieve detailed information about a specific document published in the Trust Center including metadata, content, and access settings. Use this to access individual document details for Trust Center content management. | +| Tool Name | Description | +| ------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | +| [`tests`](https://developer.vanta.com/reference/listtests) | Retrieve Vanta's automated security and compliance tests. Filter by status, integration, or framework to understand pass/fail posture quickly. | +| [`list_test_entities`](https://developer.vanta.com/reference/gettestentities) | Get resources monitored by a particular test, including failing entities that need remediation. | +| [`controls`](https://developer.vanta.com/reference/listcontrols) | List security controls in your Vanta account or retrieve a specific control by ID with framework mapping details. | +| [`list_control_tests`](https://developer.vanta.com/reference/listtestsforcontrol) | Enumerate automated tests that validate a specific control, complete with status and failing entity information. | +| [`list_control_documents`](https://developer.vanta.com/reference/listcontroldocuments) | List documents mapped to a control to locate supporting evidence quickly. | +| [`documents`](https://developer.vanta.com/reference/listdocuments) | List compliance documents or fetch details for a specific document, including metadata. | +| [`document_resources`](https://developer.vanta.com/reference/listdocumentcontrols) | Retrieve resources linked to a document (controls, links, uploads) by choosing the desired resource type. | +| [`integrations`](https://developer.vanta.com/reference/listintegrations) | List integrations connected to your Vanta account or fetch details for a specific integration, including resource kinds and connection status. | +| [`integration_resources`](https://developer.vanta.com/reference/listresourcekindsummaries) | Inspect integration resource kinds, schema information, full resource lists, or a specific resource by selecting from the supported operations. | +| [`frameworks`](https://developer.vanta.com/reference/listframeworks) | List compliance frameworks with completion status and progress metrics for each. | +| [`list_framework_controls`](https://developer.vanta.com/reference/listframeworkcontrols) | Retrieve the controls associated with a compliance framework, including descriptions and implementation guidance. | +| [`people`](https://developer.vanta.com/reference/listpeople) | List people across your organization or look up a specific person by ID with role, email, and group membership metadata. | +| [`risks`](https://developer.vanta.com/reference/listriskscenarios) | List risk scenarios under management or fetch a specific scenario to review status, scoring, and treatment plans. | +| [`vulnerabilities`](https://developer.vanta.com/reference/listvulnerabilities) | List detected vulnerabilities or retrieve a specific item with CVE metadata, severity, and impacted assets. | ## Configuration @@ -443,6 +255,7 @@ vanta-mcp-server/ │ │ └── README.md # Evaluation documentation │ ├── api.ts # Base API configuration │ ├── auth.ts # Authentication handling +│ ├── config.ts # Control enabled tools │ ├── index.ts # Main server entry point │ ├── registry.ts # Automated tool registration │ └── types.ts # Type definitions @@ -460,29 +273,6 @@ vanta-mcp-server/ - **DRY Principles**: Extensive code reuse through centralized utilities and schema factories - **Type Safety**: Full TypeScript coverage with comprehensive type definitions -### Intelligent Tool Consolidation - -The Vanta MCP Server implements a **consolidated tool architecture** where many tools can handle both list and get operations: - -**Before (53 tools):** - -- `list_document_controls`, `list_document_links`, `list_document_uploads` (3 separate tools) -- `list_integration_resource_kinds`, `get_integration_resource_kind_details`, `list_integration_resources`, `get_integration_resource` (4 separate tools) -- `list_vendor_documents`, `list_vendor_findings`, `list_vendor_security_reviews` (3 separate tools) - -**After (43 tools):** - -- `document_resources` (consolidates 3 operations with `resourceType` parameter) -- `integration_resources` (consolidates 4 operations with `operation` parameter) -- `vendor_compliance` (consolidates 3 operations with `complianceType` parameter) - -**Benefits:** - -- ✅ **Fewer Tools**: 19% reduction while maintaining all functionality -- ✅ **Clearer Intent**: Tools match natural language patterns better -- ✅ **Preserved Usability**: All original capabilities maintained -- ✅ **Intelligent Routing**: Single tool automatically routes to appropriate endpoints - For detailed architecture documentation, see [`src/operations/README.md`](src/operations/README.md). ## Debugging @@ -495,6 +285,14 @@ npx @modelcontextprotocol/inspector npx @vantasdk/vanta-mcp-server The inspector will open in your browser, allowing you to test tool calls and inspect the server's behavior. +If you want to test a local build you can do so using: + +```bash +npx @modelcontextprotocol/inspector node path/to/build/index.js +``` + +In the browser window you will then need to add the environment variable "VANTA_ENV_FILE": "/absolute/path/to/your/vanta-credentials.env" + ## Example Usage ### Get failing AWS tests for SOC2 diff --git a/src/config.ts b/src/config.ts new file mode 100644 index 0000000..c3771ef --- /dev/null +++ b/src/config.ts @@ -0,0 +1,36 @@ +const normalizeName = (name: string): string => name.trim().toLowerCase(); + +const enabledToolNames = [ + // Add tool names here to restrict the server to a subset of tools. + // Leave the array empty to enable every tool. + // Example: + // "tests", + // "list_test_entities", + "tests", + "list_test_entities", + "people", + "documents", + "document_resources", + "integrations", + "integration_resources", + "controls", + "list_control_tests", + "list_control_documents", + "vulnerabilities", + "frameworks", + "list_framework_controls", + "risks", +].map(normalizeName); + +export const enabledTools = new Set(enabledToolNames); + +export const hasEnabledToolFilter = enabledTools.size > 0; + +export const isToolEnabled = (toolName: string): boolean => { + if (!hasEnabledToolFilter) { + return true; + } + return enabledTools.has(normalizeName(toolName)); +}; + +export const getEnabledToolNames = (): string[] => [...enabledTools]; diff --git a/src/index.ts b/src/index.ts index 18e9030..c522e6c 100644 --- a/src/index.ts +++ b/src/index.ts @@ -4,6 +4,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { registerAllOperations } from "./registry.js"; import { initializeToken } from "./auth.js"; +import { getEnabledToolNames, hasEnabledToolFilter } from "./config.js"; const server = new McpServer({ name: "vanta-mcp", @@ -18,6 +19,13 @@ async function main() { // Register all tools automatically await registerAllOperations(server); + if (hasEnabledToolFilter) { + const enabledTools = getEnabledToolNames(); + console.error( + `⚠️ Tools enabled via VANTA_MCP_ENABLED_TOOLS: ${enabledTools.join(", ")}`, + ); + } + // Connect to stdio transport const transport = new StdioServerTransport(); await server.connect(transport); diff --git a/src/operations/README.md b/src/operations/README.md index af800d4..48773fc 100644 --- a/src/operations/README.md +++ b/src/operations/README.md @@ -273,8 +273,7 @@ export default { ## Automated Registration - Each operations file exports a default object `{ tools: [...] }`. -- `src/registry.ts` automatically imports every `src/operations/*.ts` module and registers the listed tools. -- Adding a new operation only requires exporting the tool and handler, then listing them in the default export. +- `src/registry.ts` automatically imports every `src/operations/*.ts` module and registers the listed tools (see Step 7 below). ## Adding or Updating Operations @@ -284,6 +283,7 @@ export default { 4. **Extend the default export** with the new tool/handler pair. 5. **Update `src/operations/index.ts`** to re-export the module (if a new file is added). 6. **Document new tools** in `README.md` (root) and update evaluation artifacts (below). +7. **Enable the tool in `src/config.ts`**. Add the tool's name to the `enabledToolNames` array to make it available through the MCP server. Leaving the array empty enables _all_ tools. ## Evaluation Suite Updates diff --git a/src/registry.ts b/src/registry.ts index 699eca0..a96e4bd 100644 --- a/src/registry.ts +++ b/src/registry.ts @@ -1,6 +1,11 @@ import { CallToolResult } from "@modelcontextprotocol/sdk/types.js"; import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { z } from "zod"; +import { + getEnabledToolNames, + hasEnabledToolFilter, + isToolEnabled, +} from "./config.js"; // Tool definition interface (matches our Tool pattern) export interface ToolDefinition { @@ -24,19 +29,35 @@ export function registerTool( server: McpServer, tool: ToolDefinition, handler: (args: z.infer) => Promise, -): void { +): boolean { + if (!isToolEnabled(tool.name)) { + console.error(`⚪️ Skipping tool not in enabled list: ${tool.name}`); + return false; + } + const parameters = tool.parameters as z.ZodObject; server.tool(tool.name, tool.description, parameters.shape, handler); + return true; } // Helper function to register all tools from a module export function registerOperationModule( server: McpServer, operationModule: OperationModule, -): void { +): { registered: number; skipped: number } { + let registered = 0; + let skipped = 0; + operationModule.tools.forEach(({ tool, handler }) => { - registerTool(server, tool, handler); + const wasRegistered = registerTool(server, tool, handler); + if (wasRegistered) { + registered += 1; + } else { + skipped += 1; + } }); + + return { registered, skipped }; } // Auto-discovery and registration of all operations @@ -66,13 +87,25 @@ export async function registerAllOperations(server: McpServer): Promise { const modules = await Promise.all(operations); let totalTools = 0; + let skippedTools = 0; modules.forEach(module => { const operationModule = module.default; - registerOperationModule(server, operationModule); - totalTools += operationModule.tools.length; + const { registered, skipped } = registerOperationModule( + server, + operationModule, + ); + totalTools += registered; + skippedTools += skipped; }); console.error( `✅ Registered ${String(totalTools)} tools from ${String(modules.length)} operation modules successfully`, ); + + if (skippedTools > 0 && hasEnabledToolFilter) { + const enabledList = getEnabledToolNames().join(", "); + console.error( + `⚠️ Tools skipped because they are not enabled: ${String(skippedTools)} (enabled list: ${enabledList})`, + ); + } } From 9360778a4b4d8eef40c96a86dd95a1ad96393f1f Mon Sep 17 00:00:00 2001 From: Garrett McCutcheon Date: Mon, 6 Oct 2025 10:39:53 -0400 Subject: [PATCH 24/24] Add and clarify optional parameters for tools --- src/operations/common/descriptions.ts | 2 +- src/operations/documents.ts | 28 ++++++++++++---- src/operations/integrations.ts | 2 +- src/operations/people.ts | 22 +++++++++---- src/operations/risks.ts | 12 +++++-- src/operations/tests.ts | 32 +++++++++++++++---- src/operations/vulnerabilities.ts | 46 +++++++++++++++++++++++---- 7 files changed, 114 insertions(+), 30 deletions(-) diff --git a/src/operations/common/descriptions.ts b/src/operations/common/descriptions.ts index b9219dc..2c171ce 100644 --- a/src/operations/common/descriptions.ts +++ b/src/operations/common/descriptions.ts @@ -2,7 +2,7 @@ // This file provides centralized, consistent descriptions for commonly used parameters // across all operations files, ensuring uniformity and maintainability. -export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of tests returned in a single response. +export const PAGE_SIZE_DESCRIPTION = `Controls the maximum number of results returned in a single response. Allowed values: 1–100. Default is 10.`; export const PAGE_CURSOR_DESCRIPTION = `A marker or pointer telling the API where to start fetching items for the diff --git a/src/operations/documents.ts b/src/operations/documents.ts index beb780e..ee572d5 100644 --- a/src/operations/documents.ts +++ b/src/operations/documents.ts @@ -13,11 +13,27 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const DocumentsInput = createConsolidatedSchema({ - paramName: "documentId", - description: DOCUMENT_ID_DESCRIPTION, - resourceName: "document", -}); +const DocumentsInput = createConsolidatedSchema( + { + paramName: "documentId", + description: DOCUMENT_ID_DESCRIPTION, + resourceName: "document", + }, + { + frameworkMatchesAny: z + .array(z.string()) + .describe( + "Filter documents by framework IDs. Returns documents that belong to any of the specified frameworks, e.g. ['soc2', 'iso27001', 'hipaa']", + ) + .optional(), + statusMatchesAny: z + .array(z.string()) + .describe( + "Filter documents by status. Possible values: Needs document, Needs update, Not relevant, OK.", + ) + .optional(), + }, +); const DocumentResourcesInput = z.object({ documentId: z.string().describe(DOCUMENT_ID_DESCRIPTION), @@ -48,7 +64,7 @@ export const DocumentsTool: Tool = { export const DocumentResourcesTool: Tool = { name: "document_resources", description: - "Access document-related resources including controls, links, and uploads. Specify resourceType to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached.", + "Access document-related resources including controls, links (i.e. hyperlinks), and uploads. Specify resourceType to get the specific type of resource associated with a document. Use this to explore what controls are linked to a document, what external references exist, or what files are attached (including the download link for those files).", parameters: DocumentResourcesInput, }; diff --git a/src/operations/integrations.ts b/src/operations/integrations.ts index 771cc4a..2b5fda6 100644 --- a/src/operations/integrations.ts +++ b/src/operations/integrations.ts @@ -29,7 +29,7 @@ const IntegrationResourcesInput = z.object({ resourceKind: z .string() .describe( - "Resource kind to operate on, e.g. 'ec2-instances' or specific resource kind identifier (required for get_kind_details, list_resources, get_resource)", + "Resource kind to operate on, e.g. 'EC2Instance' or specific resource kind identifier (required for get_kind_details, list_resources, get_resource)", ) .optional(), resourceId: z diff --git a/src/operations/people.ts b/src/operations/people.ts index 221412d..4b2d4db 100644 --- a/src/operations/people.ts +++ b/src/operations/people.ts @@ -8,12 +8,22 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const PeopleInput = createConsolidatedSchema({ - paramName: "personId", - description: - "Person ID to retrieve, e.g. 'person-123' or specific person identifier", - resourceName: "person", -}); +const PeopleInput = createConsolidatedSchema( + { + paramName: "personId", + description: + "Person ID to retrieve, e.g. 'person-123' or specific person identifier. If provided, returns the specific person, and no other parameters may be provided. If omitted, lists all people with optional filtering and pagination. ", + resourceName: "person", + }, + { + taskStatusMatchesAny: z + .array(z.string()) + .describe( + "Filter people by task status. Possible values: COMPLETED (Task is completed), IN_PROGRESS (Task is in progress), FAILED (Task failed), NOT_STARTED (Task is not started)", + ) + .optional(), + }, +); // 3. Tool Definitions export const PeopleTool: Tool = { diff --git a/src/operations/risks.ts b/src/operations/risks.ts index 956dbd2..aabbb90 100644 --- a/src/operations/risks.ts +++ b/src/operations/risks.ts @@ -12,7 +12,7 @@ const RisksInput = createConsolidatedSchema( { paramName: "riskId", description: - "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier", + "Risk scenario ID to retrieve, e.g. 'risk-scenario-123' or specific risk identifier. If provided, returns the specific risk scenario, and no other parameters may be provided. If omitted, lists all risk scenarios with optional filtering and pagination.", resourceName: "risk scenario", }, { @@ -20,8 +20,14 @@ const RisksInput = createConsolidatedSchema( .string() .optional() .describe( - "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc.", + "Filter by risk category. Example: Access Control, Cryptography, Privacy, etc. Use 'Uncategorized' for risks that don't have a category.", ), + reviewStatusMatchesAny: z + .array(z.string()) + .describe( + "Filter risk scenarios by review status. Possible values: PENDING, APPROVED, REJECTED", + ) + .optional(), }, ); @@ -29,7 +35,7 @@ const RisksInput = createConsolidatedSchema( export const RisksTool: Tool = { name: "risks", description: - "Access risk scenarios in your Vanta account. Provide riskId to get a specific risk scenario, or omit to list all risks with optional category filtering. Returns risk details, assessments, and mitigation strategies for compliance reporting.", + "Access risk scenarios in your Vanta account. Provide riskId to get a specific risk scenario, or omit to list all risks with optional filtering and pagination. Returns risk details, impact assessments, and mitigation strategies for compliance reporting.", parameters: RisksInput, }; diff --git a/src/operations/tests.ts b/src/operations/tests.ts index ae60a21..c6b8951 100644 --- a/src/operations/tests.ts +++ b/src/operations/tests.ts @@ -12,12 +12,30 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const TestsInput = createConsolidatedSchema({ - paramName: "testId", - description: - "Test ID to retrieve, e.g. 'test-123' or specific test identifier", - resourceName: "test", -}); +const TestsInput = createConsolidatedSchema( + { + paramName: "testId", + description: + "Test ID to retrieve, e.g. 'test-123' or specific test identifier. If provided, returns the specific test, and no other parameters may be provided. If omitted, lists all tests with optional filtering and pagination.", + resourceName: "test", + }, + { + statusFilter: z + .string() + .describe( + "Filter tests by test status. Possible values: OK (Test passed), DEACTIVATED (Test is deactivated), NEEDS_ATTENTION (Test failed), IN_PROGRESS (Test is in progress), INVALID (Test is invalid), NOT_APPLICABLE (Test is not applicable)", + ) + .optional(), + frameworkFilter: z + .string() + .describe("Filter tests by framework. Provide framework ID.") + .optional(), + integrationFilter: z + .string() + .describe("Filter tests by integration. Provide integration ID.") + .optional(), + }, +); const ListTestEntitiesInput = createIdWithPaginationSchema({ paramName: "testId", @@ -29,7 +47,7 @@ const ListTestEntitiesInput = createIdWithPaginationSchema({ export const TestsTool: Tool = { name: "tests", description: - "Access security tests in your Vanta account. Provide testId to get a specific test, or omit to list all tests. Returns test IDs, names, types, schedules, current status, and detailed configuration for compliance monitoring.", + "Access continuous monitoring tests in your Vanta account. Provide testId to get a specific test, or omit to list all tests. Returns test IDs, names, types, schedules, current status, and detailed configuration for compliance monitoring.", parameters: TestsInput, }; diff --git a/src/operations/vulnerabilities.ts b/src/operations/vulnerabilities.ts index 1deddfa..affb7d7 100644 --- a/src/operations/vulnerabilities.ts +++ b/src/operations/vulnerabilities.ts @@ -8,12 +8,46 @@ import { } from "./common/imports.js"; // 2. Input Schemas -const VulnerabilitiesInput = createConsolidatedSchema({ - paramName: "vulnerabilityId", - description: - "Vulnerability ID to retrieve, e.g. 'vulnerability-123' or specific vulnerability identifier", - resourceName: "vulnerability", -}); +const VulnerabilitiesInput = createConsolidatedSchema( + { + paramName: "vulnerabilityId", + description: + "Vulnerability ID to retrieve, e.g. 'vulnerability-123' or specific vulnerability identifier. If provided, returns the specific vulnerability, and no other parameters may be provided. If omitted, lists all vulnerabilities with optional filtering and pagination.", + resourceName: "vulnerability", + }, + { + externalVulnerabilityId: z + .string() + .describe( + "Filter vulnerabilities by external vulnerability ID (e.g. CVE-2024-1234). Returns vulnerabilities that match the provided external vulnerability ID.", + ) + .optional(), + severity: z + .string() + .describe( + "Filter vulnerabilities by severity. Possible values: LOW (Low severity), MEDIUM (Medium severity), HIGH (High severity), CRITICAL (Critical severity)", + ) + .optional(), + integrationId: z + .string() + .describe( + "Filter vulnerabilities by integration ID. Returns vulnerabilities that are associated with the specified integration.", + ) + .optional(), + slaDeadlineAfter: z + .string() + .describe( + "Filter vulnerabilities by SLA deadline after the specified date. Returns vulnerabilities that have an SLA deadline after the specified date. Date should be formatted as YYYY-MM-DD.", + ) + .optional(), + slaDeadlineBefore: z + .string() + .describe( + "Filter vulnerabilities by SLA deadline before the specified date. Returns vulnerabilities that have an SLA deadline before the specified date. Date should be formatted as YYYY-MM-DD.", + ) + .optional(), + }, +); // 3. Tool Definitions export const VulnerabilitiesTool: Tool = {