tools

MCP Tools & Permissions

The handler filters tools dynamically based on the Sysdig user's permissions. Each tool declares mandatory permissions via WithRequiredPermissions.

Adding a New Tool

1. See other tools: Check how other tools are implemented so you can have the context on how they should look like.

2. Create Files: Add tool_<name>.go and tool_<name>_test.go in internal/infra/mcp/tools/.

3. Implement the Tool:

   • Define a struct that holds the Sysdig client, or any required collaborator.
   • Implement the handle method, which contains the tool's core logic.
   • Implement the RegisterInServer method to define the tool's MCP schema, including its name, description, parameters, and required permissions. Use helpers from utils.go.
   • If a tool does not have any required permission, just specify WithRequiredPermissions(). If the tool requires one or multiple permissions, specify them like WithRequiredPermissions("a.permission", "another.permission").

4. Write Tests: Use Ginkgo/Gomega to write BDD-style tests. Mock the Sysdig client to cover:

   • Parameter validation
   • Permission metadata
   • Sysdig API client interactions (mocked)
   • Error handling

5. Register the Tool: Add the new tool to setupHandler() in cmd/server/main.go.

6. Document: Add the new tool to the README.md and the table in this document.

Testing Philosophy

• Use BDD-style tests with Ginkgo/Gomega
• Each tool requires comprehensive test coverage for:
  • Parameter validation (all possible combinations need to be tested)
  • Permission metadata
  • Sysdig API client interactions (mocked using go-mock)
  • Error handling
• No focused specs (FDescribe, FIt) should be committed