mcp

package
v0.0.0-...-13d30d2 Latest Latest
Warning

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

Go to latest
Published: Aug 26, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Index

Constants

View Source
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.

View Source
const ServerName = "comments-mcp-server"

Variables

View Source
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

func Probe(ctx context.Context, exePath string) (comment.MCPInfo, error)

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

func NewServer

func NewServer() *Server

NewServer creates a new MCP server for the comments tool

func (*Server) Serve

func (s *Server) Serve(ctx context.Context) error

Serve starts the MCP server using stdio transport

func (*Server) ToolNames

func (s *Server) ToolNames() []string

ToolNames returns the names of all registered tools, in registration order.

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

Jump to

Keyboard shortcuts

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