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
- Variables
- type BurndownPoint
- type Client
- func (c *Client) AcceptDrift(ctx context.Context) (string, error)
- func (c *Client) AddFeature(ctx context.Context, title, description string) (string, error)
- func (c *Client) ApprovePlan(ctx context.Context) (string, error)
- func (c *Client) AssignTask(ctx context.Context, taskID, assignee string) (string, error)
- func (c *Client) CheckPolicy(ctx context.Context) (string, error)
- func (c *Client) CheckPolicyTyped(ctx context.Context) ([]PolicyViolation, error)
- func (c *Client) Close() error
- func (c *Client) Compatible(ctx context.Context) error
- func (c *Client) DebtReport(ctx context.Context) (string, error)
- func (c *Client) DebtReportTyped(ctx context.Context) (*DebtReport, error)
- func (c *Client) DebtSummary(ctx context.Context) (string, error)
- func (c *Client) DebtSummaryTyped(ctx context.Context) (*DebtSummary, error)
- func (c *Client) DebtTrend(ctx context.Context, days int) (string, error)
- func (c *Client) DebtTrendTyped(ctx context.Context, days int) (*DebtTrend, error)
- func (c *Client) DepsGraph(ctx context.Context, checkCycles bool) (string, error)
- func (c *Client) DepsGraphTyped(ctx context.Context, checkCycles bool) (*DepsGraphResult, error)
- func (c *Client) DepsList(ctx context.Context) (string, error)
- func (c *Client) DepsScan(ctx context.Context) (string, error)
- func (c *Client) DetectDrift(ctx context.Context) (*DriftReport, error)
- func (c *Client) ExplainDrift(ctx context.Context) (string, error)
- func (c *Client) ExplainSpec(ctx context.Context) (string, error)
- func (c *Client) Forecast(ctx context.Context) (*Forecast, error)
- func (c *Client) GeneratePlan(ctx context.Context) (string, error)
- func (c *Client) GetBlockedTasks(ctx context.Context) (string, error)
- func (c *Client) GetInProgressTasks(ctx context.Context) (string, error)
- func (c *Client) GetPlan(ctx context.Context) (*Plan, error)
- func (c *Client) GetReadyTasks(ctx context.Context) (string, error)
- func (c *Client) GetSchema(ctx context.Context) (*SchemaInfo, error)
- func (c *Client) GetSnapshot(ctx context.Context) (*Snapshot, error)
- func (c *Client) GetSpec(ctx context.Context) (*Spec, error)
- func (c *Client) GetState(ctx context.Context) (*ExecutionState, error)
- func (c *Client) GetUsage(ctx context.Context) (string, error)
- func (c *Client) GitSync(ctx context.Context) (string, error)
- func (c *Client) Init(ctx context.Context, name string) (string, error)
- func (c *Client) Initialize(ctx context.Context) (*client.ServerInfo, error)
- func (c *Client) MessagingList(ctx context.Context) (string, error)
- func (c *Client) OrgDetectDrift(ctx context.Context) (string, error)
- func (c *Client) OrgPolicy(ctx context.Context) (string, error)
- func (c *Client) OrgPolicyTyped(ctx context.Context) (*OrgPolicy, error)
- func (c *Client) OrgStatus(ctx context.Context) (string, error)
- func (c *Client) OrgStatusTyped(ctx context.Context) (*OrgMetrics, error)
- func (c *Client) PluginList(ctx context.Context) (string, error)
- func (c *Client) PluginStatus(ctx context.Context) (string, error)
- func (c *Client) PluginValidate(ctx context.Context) (string, error)
- func (c *Client) QueryProject(ctx context.Context, question string) (string, error)
- func (c *Client) ReviewSpec(ctx context.Context) (*SpecReview, error)
- func (c *Client) SmartDecompose(ctx context.Context) (*SmartPlan, error)
- func (c *Client) Status(ctx context.Context, args map[string]any) (string, error)
- func (c *Client) StatusTyped(ctx context.Context, req StatusRequest) (*StatusResult, error)
- func (c *Client) StickyDrift(ctx context.Context) (string, error)
- func (c *Client) SuggestPriorities(ctx context.Context) (*PrioritySuggestions, error)
- func (c *Client) Sync(ctx context.Context, pluginPath string) (string, error)
- func (c *Client) TeamAdd(ctx context.Context, name, role string) (string, error)
- func (c *Client) TeamList(ctx context.Context) (*TeamConfig, error)
- func (c *Client) TeamRemove(ctx context.Context, name string) (string, error)
- func (c *Client) TransitionTask(ctx context.Context, taskID, event, evidence string) (string, error)
- func (c *Client) TransitionTaskTyped(ctx context.Context, req TransitionRequest) (string, error)
- func (c *Client) UpdatePlan(ctx context.Context, tasks []Task) (string, error)
- func (c *Client) WorkspacePull(ctx context.Context) (*SyncResult, error)
- func (c *Client) WorkspacePush(ctx context.Context) (*SyncResult, error)
- type Constraint
- type DebtReport
- type DebtSummary
- type DebtTrend
- type DependencySummary
- type DeprecatedField
- type DepsGraphResult
- type DriftIssue
- type DriftReport
- type ExecutionState
- type Feature
- type Forecast
- type Option
- type OrgMetrics
- type OrgPolicy
- type Plan
- type PluginHealth
- type PluginInfo
- type PolicyViolation
- type PrioritySuggestion
- type PrioritySuggestions
- type Requirement
- type ReviewFinding
- type SchemaInfo
- type SmartPlan
- type SmartTask
- type Snapshot
- type Spec
- type SpecReview
- type StatusRequest
- type StatusResult
- type StatusTask
- type SyncResult
- type Task
- type TaskResult
- type TeamConfig
- type TeamMember
- type ToolError
- type TransitionRequest
- type VelocityWindow
Constants ¶
const SupportedSchemaMajor = "1"
SupportedSchemaMajor is the major schema version this SDK supports. Compatibility requires the server's schema major version to match.
Variables ¶
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 (*Client) AcceptDrift ¶
AcceptDrift accepts drift and locks the spec snapshot.
func (*Client) AddFeature ¶
AddFeature adds a new feature to the product specification.
func (*Client) ApprovePlan ¶
ApprovePlan approves the current plan for execution.
func (*Client) AssignTask ¶
AssignTask assigns a task to a person or agent without changing its status.
func (*Client) CheckPolicy ¶
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) Compatible ¶
Compatible checks if the server schema is compatible with this SDK version. Returns nil if compatible, error with details if not.
func (*Client) DebtReport ¶
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 ¶
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) DebtTrendTyped ¶
DebtTrendTyped returns a typed debt trend.
func (*Client) DepsGraph ¶
DepsGraph returns dependency graph summary with optional cycle detection.
func (*Client) DepsGraphTyped ¶
DepsGraphTyped returns a typed dependency graph result.
func (*Client) DetectDrift ¶
func (c *Client) DetectDrift(ctx context.Context) (*DriftReport, error)
DetectDrift detects discrepancies between spec and plan.
func (*Client) ExplainDrift ¶
ExplainDrift provides an AI-generated explanation of current drift.
func (*Client) ExplainSpec ¶
ExplainSpec provides an AI-generated walkthrough of the specification.
func (*Client) GeneratePlan ¶
GeneratePlan generates a plan from the spec using 1:1 heuristic.
func (*Client) GetBlockedTasks ¶
GetBlockedTasks returns tasks that are currently blocked.
func (*Client) GetInProgressTasks ¶
GetInProgressTasks returns tasks currently in progress.
func (*Client) GetReadyTasks ¶
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 ¶
GetSnapshot returns a consistent project snapshot.
func (*Client) GetState ¶
func (c *Client) GetState(ctx context.Context) (*ExecutionState, error)
GetState retrieves the current execution state.
func (*Client) Initialize ¶
Initialize performs the MCP initialize handshake.
func (*Client) MessagingList ¶
MessagingList lists configured messaging adapters.
func (*Client) OrgDetectDrift ¶
OrgDetectDrift detects drift across all projects.
func (*Client) OrgPolicyTyped ¶
OrgPolicyTyped returns a typed org policy.
func (*Client) OrgStatusTyped ¶
func (c *Client) OrgStatusTyped(ctx context.Context) (*OrgMetrics, error)
OrgStatusTyped returns typed org metrics.
func (*Client) PluginList ¶
PluginList lists all registered plugins.
func (*Client) PluginStatus ¶
PluginStatus checks health status of plugins.
func (*Client) PluginValidate ¶
PluginValidate validates a registered plugin.
func (*Client) QueryProject ¶
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 ¶
SmartDecompose performs AI-powered context-aware task decomposition.
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 ¶
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) TeamList ¶
func (c *Client) TeamList(ctx context.Context) (*TeamConfig, error)
TeamList returns the current team configuration.
func (*Client) TeamRemove ¶
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 ¶
TransitionTaskTyped transitions a task using a typed request.
func (*Client) UpdatePlan ¶
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.
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 ¶
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 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 ¶
TeamMember represents a team member with a role.
type TransitionRequest ¶
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.