sdk

package
v0.7.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 16, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

Package sdk provides a typed Go client for the Roady MCP server.

The client wraps mcp-go/client.CallTool with one method per MCP tool, connection management, and automatic retry via fortify.

Usage:

transport, _ := client.NewStdioTransport("roady", "mcp")
c := sdk.NewClient(transport)
defer c.Close()

info, _ := c.Initialize(ctx)
spec, _ := c.GetSpec(ctx)
fmt.Println(spec.Title)

Index

Constants

View Source
const SupportedSchemaMajor = "1"

SupportedSchemaMajor is the major schema version this SDK supports. Compatibility requires the server's schema major version to match.

Variables

View Source
var ErrNoContent = errors.New("roady: empty tool result")

ErrNoContent is returned when a tool result contains no content items.

Functions

This section is empty.

Types

type BurndownPoint

type BurndownPoint struct {
	Date      string `json:"date"`
	Actual    int    `json:"actual"`
	Projected int    `json:"projected"`
}

BurndownPoint is a single point on the burndown chart.

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a typed Go client for the Roady MCP server.

func NewClient

func NewClient(transport client.Transport, opts ...Option) *Client

NewClient creates a new SDK client wrapping the given MCP transport.

func (*Client) AcceptDrift

func (c *Client) AcceptDrift(ctx context.Context) (string, error)

AcceptDrift accepts drift and locks the spec snapshot.

func (*Client) AddFeature

func (c *Client) AddFeature(ctx context.Context, title, description string) (string, error)

AddFeature adds a new feature to the product specification.

func (*Client) ApprovePlan

func (c *Client) ApprovePlan(ctx context.Context) (string, error)

ApprovePlan approves the current plan for execution.

func (*Client) AssignTask

func (c *Client) AssignTask(ctx context.Context, taskID, assignee string) (string, error)

AssignTask assigns a task to a person or agent without changing its status.

func (*Client) CheckPolicy

func (c *Client) CheckPolicy(ctx context.Context) (string, error)

CheckPolicy checks plan compliance with execution policies.

func (*Client) CheckPolicyTyped

func (c *Client) CheckPolicyTyped(ctx context.Context) ([]PolicyViolation, error)

CheckPolicyTyped returns typed policy violations.

func (*Client) Close

func (c *Client) Close() error

Close closes the underlying transport.

func (*Client) Compatible

func (c *Client) Compatible(ctx context.Context) error

Compatible checks if the server schema is compatible with this SDK version. Returns nil if compatible, error with details if not.

func (*Client) DebtReport

func (c *Client) DebtReport(ctx context.Context) (string, error)

DebtReport generates a comprehensive debt report.

func (*Client) DebtReportTyped

func (c *Client) DebtReportTyped(ctx context.Context) (*DebtReport, error)

DebtReportTyped returns a typed debt report.

func (*Client) DebtSummary

func (c *Client) DebtSummary(ctx context.Context) (string, error)

DebtSummary returns a quick overview of debt status.

func (*Client) DebtSummaryTyped

func (c *Client) DebtSummaryTyped(ctx context.Context) (*DebtSummary, error)

DebtSummaryTyped returns a typed debt summary.

func (*Client) DebtTrend

func (c *Client) DebtTrend(ctx context.Context, days int) (string, error)

DebtTrend analyzes drift trend over the given number of days.

func (*Client) DebtTrendTyped

func (c *Client) DebtTrendTyped(ctx context.Context, days int) (*DebtTrend, error)

DebtTrendTyped returns a typed debt trend.

func (*Client) DepsGraph

func (c *Client) DepsGraph(ctx context.Context, checkCycles bool) (string, error)

DepsGraph returns dependency graph summary with optional cycle detection.

func (*Client) DepsGraphTyped

func (c *Client) DepsGraphTyped(ctx context.Context, checkCycles bool) (*DepsGraphResult, error)

DepsGraphTyped returns a typed dependency graph result.

func (*Client) DepsList

func (c *Client) DepsList(ctx context.Context) (string, error)

DepsList lists all cross-repository dependencies.

func (*Client) DepsScan

func (c *Client) DepsScan(ctx context.Context) (string, error)

DepsScan scans health status of dependent repositories.

func (*Client) DetectDrift

func (c *Client) DetectDrift(ctx context.Context) (*DriftReport, error)

DetectDrift detects discrepancies between spec and plan.

func (*Client) ExplainDrift

func (c *Client) ExplainDrift(ctx context.Context) (string, error)

ExplainDrift provides an AI-generated explanation of current drift.

func (*Client) ExplainSpec

func (c *Client) ExplainSpec(ctx context.Context) (string, error)

ExplainSpec provides an AI-generated walkthrough of the specification.

func (*Client) Forecast

func (c *Client) Forecast(ctx context.Context) (*Forecast, error)

Forecast predicts project completion based on current velocity.

func (*Client) GeneratePlan

func (c *Client) GeneratePlan(ctx context.Context) (string, error)

GeneratePlan generates a plan from the spec using 1:1 heuristic.

func (*Client) GetBlockedTasks

func (c *Client) GetBlockedTasks(ctx context.Context) (string, error)

GetBlockedTasks returns tasks that are currently blocked.

func (*Client) GetInProgressTasks

func (c *Client) GetInProgressTasks(ctx context.Context) (string, error)

GetInProgressTasks returns tasks currently in progress.

func (*Client) GetPlan

func (c *Client) GetPlan(ctx context.Context) (*Plan, error)

GetPlan retrieves the current execution plan.

func (*Client) GetReadyTasks

func (c *Client) GetReadyTasks(ctx context.Context) (string, error)

GetReadyTasks returns tasks that are ready to start.

func (*Client) GetSchema

func (c *Client) GetSchema(ctx context.Context) (*SchemaInfo, error)

GetSchema reads the roady://schema resource from the server.

func (*Client) GetSnapshot

func (c *Client) GetSnapshot(ctx context.Context) (*Snapshot, error)

GetSnapshot returns a consistent project snapshot.

func (*Client) GetSpec

func (c *Client) GetSpec(ctx context.Context) (*Spec, error)

GetSpec retrieves the current product specification.

func (*Client) GetState

func (c *Client) GetState(ctx context.Context) (*ExecutionState, error)

GetState retrieves the current execution state.

func (*Client) GetUsage

func (c *Client) GetUsage(ctx context.Context) (string, error)

GetUsage retrieves project usage and telemetry statistics.

func (*Client) GitSync

func (c *Client) GitSync(ctx context.Context) (string, error)

GitSync synchronizes task statuses from git commit markers.

func (*Client) Init

func (c *Client) Init(ctx context.Context, name string) (string, error)

Init initializes a new roady project.

func (*Client) Initialize

func (c *Client) Initialize(ctx context.Context) (*client.ServerInfo, error)

Initialize performs the MCP initialize handshake.

func (*Client) MessagingList

func (c *Client) MessagingList(ctx context.Context) (string, error)

MessagingList lists configured messaging adapters.

func (*Client) OrgDetectDrift

func (c *Client) OrgDetectDrift(ctx context.Context) (string, error)

OrgDetectDrift detects drift across all projects.

func (*Client) OrgPolicy

func (c *Client) OrgPolicy(ctx context.Context) (string, error)

OrgPolicy returns merged policy for a project.

func (*Client) OrgPolicyTyped

func (c *Client) OrgPolicyTyped(ctx context.Context) (*OrgPolicy, error)

OrgPolicyTyped returns a typed org policy.

func (*Client) OrgStatus

func (c *Client) OrgStatus(ctx context.Context) (string, error)

OrgStatus returns status overview of all Roady projects.

func (*Client) OrgStatusTyped

func (c *Client) OrgStatusTyped(ctx context.Context) (*OrgMetrics, error)

OrgStatusTyped returns typed org metrics.

func (*Client) PluginList

func (c *Client) PluginList(ctx context.Context) (string, error)

PluginList lists all registered plugins.

func (*Client) PluginStatus

func (c *Client) PluginStatus(ctx context.Context) (string, error)

PluginStatus checks health status of plugins.

func (*Client) PluginValidate

func (c *Client) PluginValidate(ctx context.Context) (string, error)

PluginValidate validates a registered plugin.

func (*Client) QueryProject

func (c *Client) QueryProject(ctx context.Context, question string) (string, error)

QueryProject asks a natural language question about the project.

func (*Client) ReviewSpec

func (c *Client) ReviewSpec(ctx context.Context) (*SpecReview, error)

ReviewSpec performs an AI-powered quality review of the specification.

func (*Client) SmartDecompose

func (c *Client) SmartDecompose(ctx context.Context) (*SmartPlan, error)

SmartDecompose performs AI-powered context-aware task decomposition.

func (*Client) Status

func (c *Client) Status(ctx context.Context, args map[string]any) (string, error)

Status returns project status with optional filters.

func (*Client) StatusTyped

func (c *Client) StatusTyped(ctx context.Context, req StatusRequest) (*StatusResult, error)

StatusTyped returns project status as a typed StatusResult.

func (*Client) StickyDrift

func (c *Client) StickyDrift(ctx context.Context) (string, error)

StickyDrift returns unresolved drift items older than 7 days.

func (*Client) SuggestPriorities

func (c *Client) SuggestPriorities(ctx context.Context) (*PrioritySuggestions, error)

SuggestPriorities returns AI-powered priority suggestions for plan tasks.

func (*Client) Sync

func (c *Client) Sync(ctx context.Context, pluginPath string) (string, error)

Sync syncs the plan with an external system via a plugin binary.

func (*Client) TeamAdd

func (c *Client) TeamAdd(ctx context.Context, name, role string) (string, error)

TeamAdd adds or updates a team member with a role.

func (*Client) TeamList

func (c *Client) TeamList(ctx context.Context) (*TeamConfig, error)

TeamList returns the current team configuration.

func (*Client) TeamRemove

func (c *Client) TeamRemove(ctx context.Context, name string) (string, error)

TeamRemove removes a team member.

func (*Client) TransitionTask

func (c *Client) TransitionTask(ctx context.Context, taskID, event, evidence string) (string, error)

TransitionTask transitions a task to a new state.

func (*Client) TransitionTaskTyped

func (c *Client) TransitionTaskTyped(ctx context.Context, req TransitionRequest) (string, error)

TransitionTaskTyped transitions a task using a typed request.

func (*Client) UpdatePlan

func (c *Client) UpdatePlan(ctx context.Context, tasks []Task) (string, error)

UpdatePlan updates the plan with the given tasks.

func (*Client) WorkspacePull

func (c *Client) WorkspacePull(ctx context.Context) (*SyncResult, error)

WorkspacePull pulls remote .roady/ changes with conflict detection.

func (*Client) WorkspacePush

func (c *Client) WorkspacePush(ctx context.Context) (*SyncResult, error)

WorkspacePush commits and pushes .roady/ changes to git remote.

type Constraint

type Constraint struct {
	ID          string `json:"id"`
	Type        string `json:"type"`
	Description string `json:"description"`
}

Constraint represents a project constraint.

type DebtReport

type DebtReport struct {
	TotalIssues    int            `json:"total_issues"`
	Categories     map[string]int `json:"categories"`
	TopDebtors     []any          `json:"top_debtors"`
	HealthLevel    string         `json:"health_level"`
	Recommendation string         `json:"recommendation"`
}

DebtReport represents a comprehensive debt report.

type DebtSummary

type DebtSummary struct {
	TotalIssues int    `json:"total_issues"`
	HealthLevel string `json:"health_level"`
	TopDebtor   string `json:"top_debtor"`
}

DebtSummary is a quick overview of debt status.

type DebtTrend

type DebtTrend struct {
	Days       int    `json:"days"`
	DataPoints []any  `json:"data_points"`
	Direction  string `json:"direction"`
}

DebtTrend represents drift trend over time.

type DependencySummary

type DependencySummary struct {
	TotalDeps     int `json:"total_deps"`
	HealthyDeps   int `json:"healthy_deps"`
	UnhealthyDeps int `json:"unhealthy_deps"`
}

DependencySummary is a dependency summary.

type DeprecatedField

type DeprecatedField struct {
	Tool      string `json:"tool"`
	Field     string `json:"field"`
	Since     string `json:"since"`
	RemovedIn string `json:"removed_in"`
	Migration string `json:"migration"`
}

DeprecatedField records a field or tool that has been deprecated.

type DepsGraphResult

type DepsGraphResult struct {
	Summary  DependencySummary `json:"summary"`
	HasCycle *bool             `json:"has_cycle,omitempty"`
}

DepsGraphResult is the dependency graph result.

type DriftIssue

type DriftIssue struct {
	ID          string `json:"id"`
	Type        string `json:"type"`
	Category    string `json:"category"`
	Severity    string `json:"severity"`
	ComponentID string `json:"component_id"`
	Message     string `json:"message"`
	Path        string `json:"path"`
	Hint        string `json:"hint"`
}

DriftIssue represents a single drift issue.

type DriftReport

type DriftReport struct {
	ID        string       `json:"id"`
	Issues    []DriftIssue `json:"issues"`
	CreatedAt time.Time    `json:"created_at"`
}

DriftReport represents a drift detection report.

type ExecutionState

type ExecutionState struct {
	ProjectID  string                `json:"project_id"`
	TaskStates map[string]TaskResult `json:"task_states"`
	UpdatedAt  time.Time             `json:"updated_at"`
}

ExecutionState represents the current execution state.

type Feature

type Feature struct {
	ID           string        `json:"id"`
	Title        string        `json:"title"`
	Description  string        `json:"description"`
	Requirements []Requirement `json:"requirements"`
}

Feature represents a product feature.

type Forecast

type Forecast struct {
	Remaining      int              `json:"remaining"`
	Completed      int              `json:"completed"`
	Total          int              `json:"total"`
	Velocity       float64          `json:"velocity"`
	EstimatedDays  float64          `json:"estimated_days"`
	CompletionRate float64          `json:"completion_rate"`
	Trend          string           `json:"trend"`
	TrendSlope     float64          `json:"trend_slope"`
	Confidence     float64          `json:"confidence"`
	CILow          float64          `json:"ci_low"`
	CIExpected     float64          `json:"ci_expected"`
	CIHigh         float64          `json:"ci_high"`
	Burndown       []BurndownPoint  `json:"burndown"`
	Windows        []VelocityWindow `json:"windows"`
	DataPoints     int              `json:"data_points"`
}

Forecast represents a project completion forecast.

type Option

type Option func(*options)

Option configures the SDK client.

func WithRetry

func WithRetry(maxAttempts int, initialDelay time.Duration) Option

WithRetry configures retry behaviour.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the per-call timeout.

type OrgMetrics

type OrgMetrics struct {
	Projects []any `json:"projects"`
}

OrgMetrics represents org-level aggregated metrics.

type OrgPolicy

type OrgPolicy struct {
	MaxWIP      int  `json:"max_wip"`
	AllowAI     bool `json:"allow_ai"`
	TokenLimit  int  `json:"token_limit"`
	BudgetHours int  `json:"budget_hours"`
}

OrgPolicy represents merged policy for a project.

type Plan

type Plan struct {
	ID             string    `json:"id"`
	SpecID         string    `json:"spec_id"`
	Tasks          []Task    `json:"tasks"`
	ApprovalStatus string    `json:"approval_status"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

Plan represents an execution plan.

type PluginHealth

type PluginHealth struct {
	Name    string `json:"name"`
	Healthy bool   `json:"healthy"`
	Message string `json:"message"`
}

PluginHealth represents plugin health status.

type PluginInfo

type PluginInfo struct {
	Name   string `json:"name"`
	Path   string `json:"path"`
	Status string `json:"status"`
}

PluginInfo represents plugin information.

type PolicyViolation

type PolicyViolation struct {
	Rule    string `json:"rule"`
	Message string `json:"message"`
}

PolicyViolation represents a policy compliance violation.

type PrioritySuggestion

type PrioritySuggestion struct {
	TaskID            string `json:"task_id"`
	CurrentPriority   string `json:"current_priority"`
	SuggestedPriority string `json:"suggested_priority"`
	Reason            string `json:"reason"`
}

PrioritySuggestion represents an AI suggestion to change a task's priority.

type PrioritySuggestions

type PrioritySuggestions struct {
	Suggestions []PrioritySuggestion `json:"suggestions"`
	Summary     string               `json:"summary"`
}

PrioritySuggestions is the result of an AI priority analysis.

type Requirement

type Requirement struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Priority    string   `json:"priority"`
	Estimate    string   `json:"estimate"`
	DependsOn   []string `json:"depends_on"`
}

Requirement represents a feature requirement.

type ReviewFinding

type ReviewFinding struct {
	Category   string `json:"category"`
	Severity   string `json:"severity"`
	FeatureID  string `json:"feature_id"`
	Title      string `json:"title"`
	Suggestion string `json:"suggestion"`
}

ReviewFinding represents a single quality finding in a spec review.

type SchemaInfo

type SchemaInfo struct {
	SchemaVersion string            `json:"schema_version"`
	ServerVersion string            `json:"server_version"`
	Deprecated    []DeprecatedField `json:"deprecated"`
	Changelog     string            `json:"changelog"`
}

SchemaInfo describes the MCP schema version and deprecation info.

type SmartPlan

type SmartPlan struct {
	Tasks   []SmartTask `json:"tasks"`
	Summary string      `json:"summary"`
}

SmartPlan is a plan generated with codebase context.

type SmartTask

type SmartTask struct {
	Task
	Files      []string `json:"files,omitempty"`
	Complexity string   `json:"complexity,omitempty"`
}

SmartTask is a task with codebase-aware fields.

type Snapshot

type Snapshot struct {
	Progress      float64  `json:"progress"`
	UnlockedTasks []string `json:"unlocked_tasks"`
	BlockedTasks  []string `json:"blocked_tasks"`
	InProgress    []string `json:"in_progress"`
	Completed     []string `json:"completed"`
	Verified      []string `json:"verified"`
	TotalTasks    int      `json:"total_tasks"`
	SnapshotTime  string   `json:"snapshot_time"`
}

Snapshot represents a project snapshot.

type Spec

type Spec struct {
	ID          string       `json:"id"`
	Title       string       `json:"title"`
	Description string       `json:"description"`
	Features    []Feature    `json:"features"`
	Constraints []Constraint `json:"constraints"`
	Version     string       `json:"version"`
}

Spec represents a product specification.

type SpecReview

type SpecReview struct {
	Score    int             `json:"score"`
	Summary  string          `json:"summary"`
	Findings []ReviewFinding `json:"findings"`
}

SpecReview represents the result of an AI quality review of a spec.

type StatusRequest

type StatusRequest struct {
	Status   string `json:"status,omitempty"`
	Priority string `json:"priority,omitempty"`
	Ready    bool   `json:"ready,omitempty"`
	Blocked  bool   `json:"blocked,omitempty"`
	Active   bool   `json:"active,omitempty"`
	Limit    int    `json:"limit,omitempty"`
}

StatusRequest provides typed parameters for the Status method.

type StatusResult

type StatusResult struct {
	TotalTasks    int            `json:"total_tasks"`
	FilteredCount int            `json:"filtered_count"`
	Counts        map[string]int `json:"counts"`
	Tasks         []StatusTask   `json:"tasks"`
}

StatusResult represents project status output.

type StatusTask

type StatusTask struct {
	ID       string `json:"id"`
	Title    string `json:"title"`
	Status   string `json:"status"`
	Priority string `json:"priority"`
	Unlocked bool   `json:"unlocked,omitempty"`
}

StatusTask is a task entry in status output.

type SyncResult

type SyncResult struct {
	Action   string   `json:"action"`
	Files    []string `json:"files,omitempty"`
	Conflict bool     `json:"conflict"`
	Message  string   `json:"message"`
}

SyncResult holds the outcome of a workspace push or pull.

type Task

type Task struct {
	ID          string   `json:"id"`
	Title       string   `json:"title"`
	Description string   `json:"description"`
	Priority    string   `json:"priority"`
	Estimate    string   `json:"estimate"`
	DependsOn   []string `json:"depends_on"`
	FeatureID   string   `json:"feature_id"`
}

Task represents a plan task.

type TaskResult

type TaskResult struct {
	Status   string   `json:"status"`
	Path     string   `json:"path"`
	Owner    string   `json:"owner"`
	Evidence []string `json:"evidence"`
}

TaskResult represents the status of a single task.

type TeamConfig

type TeamConfig struct {
	Members []TeamMember `json:"members"`
}

TeamConfig holds the team configuration.

type TeamMember

type TeamMember struct {
	Name string `json:"name"`
	Role string `json:"role"`
}

TeamMember represents a team member with a role.

type ToolError

type ToolError struct {
	Tool    string
	Message string
}

ToolError is returned when a tool call returns an error result.

func (*ToolError) Error

func (e *ToolError) Error() string

type TransitionRequest

type TransitionRequest struct {
	TaskID   string
	Event    string
	Evidence string
	Actor    string
}

TransitionRequest provides typed parameters for task transitions.

type VelocityWindow

type VelocityWindow struct {
	Days     int     `json:"days"`
	Velocity float64 `json:"velocity"`
	Count    int     `json:"count"`
}

VelocityWindow is a velocity measurement window.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL