Skip to content

Conversation

@cchristous
Copy link
Contributor

Summary

Adds three new MCP tools for managing Semaphore scheduled tasks (periodics):

  • tasks_list: List scheduled tasks for a project with pagination
  • tasks_describe: Get task details including recent trigger history
  • tasks_run: Trigger a task to run immediately

Why These Changes Are Safe

Security Controls

  • UUID validation: All ID parameters validated via regex patterns at schema level and handler level
  • RBAC enforcement: project.scheduler.view required for list/describe, project.scheduler.run_manually for run
  • Feature flag gating: Read operations gated by mcp_server_read_tools, write operations by mcp_server_write_tools
  • Path traversal protection: pipeline_file parameter rejects absolute paths, .. sequences, backslashes, and control characters
  • Parameter validation: Task parameters must start with letter/underscore, no control characters, max 128 char names

Implementation Safety

  • Follows established patterns from existing MCP tools (jobs, pipelines, workflows)
  • All proto getters use nil-safe Get*() methods
  • Explicit nil checks on proto messages and slice elements
  • Context timeouts on all gRPC calls via CallTimeout()
  • Response truncation prevents oversized outputs

Test Coverage

  • 7 unit tests covering:
    • Feature flag disabled scenarios
    • Successful list/describe/run operations
    • Missing required parameters
    • Invalid UUID validation
    • Write feature flag for run tool

Files Changed

File Purpose
pkg/tools/tasks/*.go Tool implementations (list, describe, run)
pkg/internal_api/periodic_scheduler/*.go gRPC client stubs
pkg/internalapi/config.go Scheduler endpoint configuration
pkg/internalapi/manager.go Provider interface + Manager
test/support/*.go Test mocks and stubs
Makefile Proto generation modules
README.md Tool documentation

Test plan

  • Unit tests pass (go test ./pkg/tools/tasks/...)
  • Full test suite passes (make test)
  • Lint passes (make lint)
  • Manual testing with MCP client against staging environment
  • Verify RBAC denies access without proper permissions
  • Verify feature flags properly gate tool availability

Add three new MCP tools for managing Semaphore scheduled tasks (periodics):

- tasks_list: List scheduled tasks for a project with pagination
- tasks_describe: Get task details including recent trigger history
- tasks_run: Trigger a task to run immediately

Key implementation details:
- Integrates PeriodicScheduler gRPC service
- Enforces RBAC permissions (project.scheduler.view, project.scheduler.run_manually)
- Feature flag gating (mcp_server_read_tools, mcp_server_write_tools)
- UUID validation on all ID parameters
- Path traversal protection for pipeline_file overrides
- Parameter name/value validation for tasks_run
The previous code used rune(name[0]) which only reads the first byte,
incorrectly interpreting multi-byte UTF-8 characters. This fix properly
decodes the first rune using utf8.DecodeRuneInString.

Added comprehensive tests for validateParameterName covering valid names,
invalid starts (numbers, special chars, multi-byte UTF-8), control
characters, and length validation.
@cchristous cchristous marked this pull request as ready for review February 5, 2026 02:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: Backlog

Development

Successfully merging this pull request may close these issues.

1 participant