Documentation
¶
Index ¶
- Constants
- Variables
- func Probe(ctx context.Context, exePath string) (comment.MCPInfo, error)
- type AcceptSuggestionRequest
- type AddCommentRequest
- type AnalyzeRequest
- type BatchAcceptRequest
- type BatchAddRequest
- type BatchCommentData
- type BatchReplyData
- type BatchReplyRequest
- type BundleIndexRequest
- type ChangedSince
- type CheckReviewRequest
- type CommentWithContext
- type ContextRequest
- type DocumentStatus
- type GateRequest
- type GetCommentRequest
- type GetTemplateRequest
- type InboxRequest
- type ListCommentsRequest
- type NewDocumentRequest
- type ReanchorMove
- type ReanchorRequest
- type RejectSuggestionRequest
- type ReplyRequest
- type RequestReviewRequest
- type ResolveRequest
- type Server
- type StatusRequest
- type SuggestRequest
- type ValidateRequest
Constants ¶
const ProbeTimeout = 10 * time.Second
ProbeTimeout bounds the doctor's MCP handshake so a wedged server reports a failed check instead of hanging the command.
const ServerName = "comments-mcp-server"
Variables ¶
var ServerVersion = "dev"
ServerVersion is what the MCP server advertises in its handshake. main sets it to the binary's stamped version at startup so the two cannot disagree — a stale server version is exactly what `comments doctor` exists to catch.
Functions ¶
func Probe ¶
Probe starts `<exePath> serve-mcp`, completes a handshake and counts the advertised tools. It uses the SDK client, which tries the stateless server/discover (SEP-2575) first and falls back to the legacy initialize handshake, so the probe follows whatever the server actually supports.
It satisfies comment.MCPProbe and is injected into the doctor run: the check logic lives in pkg/comment and must not import this package.
Types ¶
type AcceptSuggestionRequest ¶
type AcceptSuggestionRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
SuggestionID string `json:"suggestion_id" jsonschema:"ID of the suggestion to accept"`
Preview bool `json:"preview,omitempty" jsonschema:"If true preview the change without applying it"`
}
AcceptSuggestionRequest represents a request to accept a suggestion
type AddCommentRequest ¶
type AddCommentRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Author string `json:"author" jsonschema:"Author of the comment"`
Text string `json:"text" jsonschema:"Comment text"`
Type string `json:"type,omitempty" jsonschema:"Comment type: Q (Question) S (Suggestion) B (Bug) T (TODO) E (Enhancement)"`
Line int `json:"line,omitempty" jsonschema:"Line number (use exactly one of line / section / anchor)"`
Section string `json:"section,omitempty" jsonschema:"Section path (e.g. 'Introduction > Overview')"`
Anchor string `` /* 148-byte string literal not displayed */
Status string `json:"status,omitempty" jsonschema:"Status: active (default) resolved completed"`
Priority string `json:"priority,omitempty" jsonschema:"Priority: low medium (default) high"`
Blocking bool `json:"blocking,omitempty" jsonschema:"If true this comment must be resolved before the review gate passes"`
}
AddCommentRequest represents a request to add a root comment
type AnalyzeRequest ¶
type AnalyzeRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown artifact"`
Against string `json:"against,omitempty" jsonschema:"Research document to check plan coverage against"`
Template string `json:"template,omitempty" jsonschema:"Template name (defaults to frontmatter, legacy sidecar, or bundle)"`
}
AnalyzeRequest asks for deterministic artifact coverage. It is advisory and never mutates the review gate.
type BatchAcceptRequest ¶
type BatchAcceptRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
SuggestionIDs []string `json:"suggestion_ids,omitempty" jsonschema:"Explicit suggestion IDs to accept"`
Author string `json:"author,omitempty" jsonschema:"Accept all pending suggestions from this author"`
Type string `json:"type,omitempty" jsonschema:"Accept all pending suggestions of this type (Q, S, B, T, E)"`
}
BatchAcceptRequest accepts several suggestions in one call, either by an explicit ID list or by matching pending suggestions on author/type.
type BatchAddRequest ¶
type BatchAddRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Comments []BatchCommentData `json:"comments" jsonschema:"Array of comment objects to add"`
}
BatchAddRequest represents a request to add multiple comments
type BatchCommentData ¶
type BatchCommentData struct {
Author string `json:"author" jsonschema:"Author of the comment"`
Text string `json:"text" jsonschema:"Comment text"`
Type string `json:"type,omitempty" jsonschema:"Comment type (Q S B T E)"`
Line int `json:"line,omitempty" jsonschema:"Line number"`
Section string `json:"section,omitempty" jsonschema:"Section path"`
Anchor string `json:"anchor,omitempty" jsonschema:"Quote of the target line (or a unique substring); alternative to line/section"`
Status string `json:"status,omitempty" jsonschema:"Status (active resolved completed)"`
Priority string `json:"priority,omitempty" jsonschema:"Priority (low medium high)"`
Blocking bool `json:"blocking,omitempty" jsonschema:"If true this comment must be resolved before the review gate passes"`
IsSuggestion bool `json:"is_suggestion,omitempty" jsonschema:"True if this is an edit suggestion"`
StartLine int `json:"start_line,omitempty" jsonschema:"Start line for suggestion"`
EndLine int `json:"end_line,omitempty" jsonschema:"End line for suggestion"`
OriginalText string `json:"original_text,omitempty" jsonschema:"Original text for suggestion"`
ProposedText string `json:"proposed_text,omitempty" jsonschema:"Proposed text for suggestion"`
}
BatchCommentData represents a single comment in a batch add operation
type BatchReplyData ¶
type BatchReplyData struct {
ThreadID string `json:"thread_id" jsonschema:"ID of the thread to reply to"`
Author string `json:"author" jsonschema:"Author of the reply"`
Text string `json:"text" jsonschema:"Reply text"`
}
BatchReplyData represents a single reply in a batch reply operation
type BatchReplyRequest ¶
type BatchReplyRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Replies []BatchReplyData `json:"replies" jsonschema:"Array of reply objects to add"`
}
BatchReplyRequest represents a request to add multiple replies
type BundleIndexRequest ¶
type BundleIndexRequest struct {
Path string `json:"path,omitempty" jsonschema:"Path used to discover .comments/bundle.yaml; defaults to current directory"`
}
type ChangedSince ¶
type ChangedSince struct {
Reviewer string `json:"reviewer"`
ChangedLines int `json:"changed_lines"` // lines added or edited
Deletions int `json:"deletions"` // pure removals (not beside an edit, which counts once as the edit)
ChangedSections []string `json:"changed_sections"` // innermost section paths touched, in document order
}
ChangedSince reports what moved in the document since a reviewer's last verdict (approved / changes_requested — a commented reply-pass does not move the baseline). Absent when that reviewer has never signed off.
type CheckReviewRequest ¶
type CheckReviewRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file under review"`
Since string `` /* 165-byte string literal not displayed */
Strict bool `json:"strict,omitempty" jsonschema:"If true evaluate the gate with strict rules once the review completes"`
}
CheckReviewRequest polls a review handle created by a non-blocking comments_request_review call (or any RFC3339 timestamp the agent recorded).
type CommentWithContext ¶
type CommentWithContext struct {
Comment comment.CommentView `json:"comment"`
SectionPath string `json:"section_path,omitempty"`
ContextLines []string `json:"context_lines,omitempty"`
IsOrphaned bool `json:"is_orphaned,omitempty"`
}
CommentWithContext represents a comment with its surrounding context
type ContextRequest ¶
type ContextRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the current OKF concept"`
For string `` /* 129-byte string literal not displayed */
IncludeBody bool `json:"include_body,omitempty" jsonschema:"Include document bodies"`
IncludeThreads bool `json:"include_threads,omitempty" jsonschema:"Include review comment threads"`
}
ContextRequest retrieves the relevant OKF neighborhood for an agent role.
type DocumentStatus ¶
type DocumentStatus struct {
FilePath string `json:"filepath"`
TotalThreads int `json:"total_threads"`
TotalComments int `json:"total_comments"`
ResolvedThreads int `json:"resolved_threads"`
UnresolvedThreads int `json:"unresolved_threads"`
PendingSuggestions int `json:"pending_suggestions"`
OrphanedComments int `json:"orphaned_comments"`
IsStale bool `json:"is_stale"`
DocumentHash string `json:"document_hash"`
LastValidated string `json:"last_validated"`
SuggestionsByAuthor map[string]int `json:"suggestions_by_author,omitempty"`
ChangedSince *ChangedSince `json:"changed_since,omitempty"`
}
DocumentStatus represents the status of a document's comments
type GateRequest ¶
type GateRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to a markdown file or a directory of markdown files"`
Strict bool `json:"strict,omitempty" jsonschema:"If true fail on any unresolved comment or pending suggestion not just blocking ones"`
Template string `` /* 137-byte string literal not displayed */
}
GateRequest represents a request to evaluate the review gate
type GetCommentRequest ¶
type GetCommentRequest struct {
FilePath string `json:"filepath,omitempty" jsonschema:"Path to the markdown file (or use cite)"`
CommentID string `json:"comment_id,omitempty" jsonschema:"ID of the comment to retrieve (or use cite)"`
Cite string `` /* 153-byte string literal not displayed */
From string `` /* 130-byte string literal not displayed */
}
GetCommentRequest represents a request to get a specific comment with context
type GetTemplateRequest ¶
type GetTemplateRequest struct {
Name string `json:"name,omitempty" jsonschema:"Template name; omit to list available templates"`
}
GetTemplateRequest represents a request to read a template definition
type InboxRequest ¶
type InboxRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to a markdown file or a directory of markdown files"`
Since string `` /* 190-byte string literal not displayed */
}
InboxRequest asks "what needs my attention" across a file or directory.
type ListCommentsRequest ¶
type ListCommentsRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Author string `json:"author,omitempty" jsonschema:"Filter by author name"`
Type string `json:"type,omitempty" jsonschema:"Filter by comment type (Q S B T E)"`
Section string `json:"section,omitempty" jsonschema:"Filter by section path (e.g. 'Introduction > Overview')"`
Search string `json:"search,omitempty" jsonschema:"Search in comment text"`
Status string `json:"status,omitempty" jsonschema:"Filter by status (active orphaned resolved completed)"`
Priority string `json:"priority,omitempty" jsonschema:"Filter by priority (low medium high)"`
Resolved *bool `json:"resolved,omitempty" jsonschema:"Filter by resolved state"`
LineStart int `json:"line_start,omitempty" jsonschema:"Filter comments from this line"`
LineEnd int `json:"line_end,omitempty" jsonschema:"Filter comments up to this line"`
WithContext bool `json:"with_context,omitempty" jsonschema:"Include surrounding context for each comment"`
}
ListCommentsRequest represents a request to list/filter comments
type NewDocumentRequest ¶
type NewDocumentRequest struct {
Name string `json:"name" jsonschema:"Lowercase document slug without .md"`
Template string `json:"template" jsonschema:"Template that selects the bundle collection and document shape"`
Title string `json:"title,omitempty" jsonschema:"Document title; defaults to the slug"`
Description string `json:"description,omitempty" jsonschema:"One-sentence concept description"`
From string `json:"from,omitempty" jsonschema:"Related source document to record as informed_by"`
BundlePath string `` /* 130-byte string literal not displayed */
}
NewDocumentRequest creates a concept through the project's OKF bundle.
type ReanchorMove ¶
type ReanchorMove struct {
CommentID string `json:"comment_id" jsonschema:"ID of the comment to move"`
Line int `json:"line,omitempty" jsonschema:"New line number (use line OR section)"`
Section string `json:"section,omitempty" jsonschema:"New section path (use line OR section)"`
}
ReanchorMove relocates one comment to its new position after an agent edit
type ReanchorRequest ¶
type ReanchorRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Moves []ReanchorMove `json:"moves" jsonschema:"Comments to relocate to their new lines/sections"`
}
ReanchorRequest migrates comment anchors after the agent edited the document. The editing agent knows how its edits moved text, so it migrates the anchors it displaced; the load-time cascade is only the safety net.
type RejectSuggestionRequest ¶
type RejectSuggestionRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
SuggestionID string `json:"suggestion_id" jsonschema:"ID of the suggestion to reject"`
}
RejectSuggestionRequest represents a request to reject a suggestion
type ReplyRequest ¶
type ReplyRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
ThreadID string `json:"thread_id" jsonschema:"ID of the thread to reply to"`
Author string `json:"author" jsonschema:"Author of the reply"`
Text string `json:"text" jsonschema:"Reply text"`
}
ReplyRequest represents a request to reply to a thread
type RequestReviewRequest ¶
type RequestReviewRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file to be reviewed"`
TimeoutSeconds int `json:"timeout_seconds,omitempty" jsonschema:"Max seconds to wait for the human signoff (default 600; blocking mode only)"`
Strict bool `json:"strict,omitempty" jsonschema:"If true evaluate the gate with strict rules after signoff"`
Blocking *bool `` /* 162-byte string literal not displayed */
}
RequestReviewRequest represents a request for human review. By default it blocks until signoff; with blocking=false it returns a durable handle (the `since` timestamp) for later comments_check_review polling.
type ResolveRequest ¶
type ResolveRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
ThreadID string `json:"thread_id" jsonschema:"ID of the thread to resolve"`
Unresolve bool `json:"unresolve,omitempty" jsonschema:"Set to true to unresolve the thread"`
}
ResolveRequest represents a request to resolve/unresolve a thread
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server wraps the MCP server and provides comment-specific functionality
type StatusRequest ¶
type StatusRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Reviewer string `` /* 196-byte string literal not displayed */
}
StatusRequest represents a request to get document status
type SuggestRequest ¶
type SuggestRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Author string `json:"author" jsonschema:"Author of the suggestion"`
Text string `json:"text" jsonschema:"Description of the suggestion"`
StartLine int `json:"start_line,omitempty" jsonschema:"Start line of the edit (or use anchor)"`
EndLine int `json:"end_line,omitempty" jsonschema:"End line of the edit (or use anchor)"`
Anchor string `` /* 131-byte string literal not displayed */
OriginalText string `json:"original_text,omitempty" jsonschema:"Original text being replaced (optional for verification)"`
ProposedText string `json:"proposed_text" jsonschema:"Proposed replacement text"`
}
SuggestRequest represents a request to create an edit suggestion
type ValidateRequest ¶
type ValidateRequest struct {
FilePath string `json:"filepath" jsonschema:"Path to the markdown file"`
Template string `json:"template,omitempty" jsonschema:"Template name (defaults to frontmatter, legacy sidecar, or bundle)"`
}
ValidateRequest represents a request to validate a document against a template