Megaraptor MCP

Instructions

Implementation Reference

• src/megaraptor_mcp/tools/artifacts.py:110-181 (handler)

  Implementation of the `get_artifact` tool which retrieves the full definition of a Velociraptor artifact using a VQL query.

  @mcp.tool()
  async def get_artifact(artifact_name: str) -> list[TextContent]:
      """Get the full definition of a Velociraptor artifact.
  
      Args:
          artifact_name: The name of the artifact (e.g., 'Windows.System.Pslist')
  
      Returns:
          Complete artifact definition including parameters, sources, and VQL.
      """
      try:
          # Validate artifact_name
          if not artifact_name or not artifact_name.strip():
              return [TextContent(
                  type="text",
                  text=json.dumps({
                      "error": "Artifact name cannot be empty",
                      "hint": "Use list_artifacts tool to find available artifacts"
                  })
              )]
  
          client = get_client()
  
          vql = f"SELECT * FROM artifact_definitions(names='{artifact_name}')"
          results = client.query(vql)
  
          if not results:
              return [TextContent(
                  type="text",
                  text=json.dumps({
                      "error": f"Artifact '{artifact_name}' not found",
                      "hint": "Use list_artifacts tool to find available artifacts"
                  })
              )]
  
          artifact = results[0]
  
          # Format the output
          formatted = {
              "name": artifact.get("name", ""),
              "description": artifact.get("description", ""),
              "type": artifact.get("type", ""),
              "author": artifact.get("author", ""),
              "parameters": artifact.get("parameters", []),
              "sources": artifact.get("sources", []),
              "precondition": artifact.get("precondition", ""),
              "required_permissions": artifact.get("required_permissions", []),
          }
  
          return [TextContent(
              type="text",
              text=json.dumps(formatted, indent=2, default=str)
          )]
  
      except grpc.RpcError as e:
          # gRPC errors
          error_info = map_grpc_error(e, f"fetching artifact '{artifact_name}'")
          return [TextContent(
              type="text",
              text=json.dumps(error_info, indent=2)
          )]
  
      except Exception:
          # Generic errors - don't expose internals
          return [TextContent(
              type="text",
              text=json.dumps({
                  "error": "Failed to get artifact definition",
                  "hint": "Check Velociraptor server connection and try again"
              })
          )]