mcpserver

package
v0.7.1 Latest Latest
Warning

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

 Go to latest Published: Jul 19, 2026 License: MIT Imports: 11 Imported by: 0

Documentation

Overview

Package mcpserver exposes GitContribute application capabilities through the Model Context Protocol.

Reader tools and resources are local and offline. Operator tools declare network reads, local writes, durable jobs, or process execution through distinct interfaces and MCP annotations. Protocol payloads are mapped to product-owned application contracts rather than implementing use cases here.

Index

Constants

View Source 
const (
	ToolSearchRepositories       = "corpus.search_repositories"
	ToolSearchThreads            = "corpus.search_threads"
	ToolSearchCode               = "corpus.search_code"
	ToolGetRepositories          = "corpus.get_repositories"
	ToolGetThreads               = "corpus.get_threads"
	ToolRankThreads              = "corpus.rank_threads"
	ToolFindPrecedents           = "corpus.find_precedents"
	ToolGetRepositoryDossier     = "corpus.get_repository_dossier"
	ToolExplainMatch             = "corpus.explain_match"
	ToolGetInvestigation         = "corpus.get_investigation"
	ToolListOpportunities        = "corpus.list_opportunities"
	ToolGetOpportunity           = "corpus.get_opportunity"
	ToolGetEvidence              = "corpus.get_evidence"
	ToolGetReadiness             = "corpus.get_readiness"
	ToolFindClusters             = "corpus.find_clusters"
	ToolFindNeighbors            = "corpus.find_neighbors"
	ToolGetCoverage              = "corpus.get_coverage"
	ToolGetLens                  = "corpus.get_lens"
	ToolBuildRepositoryDossier   = "corpus.build_repository_dossier"
	ToolGetJob                   = "jobs.get"
	ToolCancelJob                = "jobs.cancel"
	ToolSearchGitHubRepositories = "github.search_repositories"
	ToolSyncRepositoryMetadata   = "github.sync_repository_metadata"
	ToolSyncThreads              = "github.sync_threads"
	ToolHydrateThreads           = "github.hydrate_threads"
	ToolGetAuthenticatedIdentity = "github.get_authenticated_identity"
	ToolSyncAuthoredPullRequests = "github.sync_authored_pull_requests"
	ToolSyncPullRequestStatus    = "github.sync_pull_request_status"
	ToolListPullRequestPortfolio = "corpus.list_pull_request_portfolio"
	ToolFindPortfolioOverlaps    = "corpus.find_portfolio_overlaps"
	ToolIndexRepositories        = "code.index_repositories"
	ToolCheckMergeConflicts      = "workspace.check_merge_conflicts"
	ToolQueryDeepWiki            = "research.query_deepwiki"
	ToolCreateWorkspace          = "workspace.create"
	ToolDefineValidation         = "validation.define"
	ToolRunValidation            = "validation.run"
	ToolStartInvestigation       = "workflow.start_investigation"
	ToolRecordHypothesis         = "workflow.record_hypothesis"
	ToolCheckDuplicates          = "workflow.check_duplicates"
	ToolFindCompetingWork        = "workflow.find_competing_work"
	ToolPromoteOpportunity       = "workflow.promote_opportunity"
	ToolPrepareContribution      = "workflow.prepare_contribution"
	ToolLinkPullRequest          = "workflow.link_pull_request"
)

Canonical MCP tool names group operations by capability and side-effect boundary.

Variables

View Source 
var ErrNotFound = errors.New("not found")

ErrNotFound lets readers distinguish absent corpus objects from failures.

Functions

func InvalidArgument added in v0.7.0 

func InvalidArgument(field, message string, example map[string]any) error

InvalidArgument reports one agent-correctable request error.

Types

type AuthenticatedIdentityOutput added in v0.5.0 

type AuthenticatedIdentityOutput struct {
	Login      string `json:"login"`
	ID         int64  `json:"id"`
	NodeID     string `json:"node_id,omitempty"`
	ObservedAt string `json:"observed_at"`
}

AuthenticatedIdentityOutput identifies the account associated with active credentials.

type BatchItem added in v0.5.0 

type BatchItem[T any] struct {
	Key          string `json:"key"`
	Status       string `json:"status"`
	Value        *T     `json:"value,omitempty"`
	Reason       string `json:"reason,omitempty"`
	Message      string `json:"message,omitempty"`
	RetryAfterMS int    `json:"retry_after_ms,omitempty"`
	NextAction   string `json:"next_action,omitempty"`
}

BatchItem reports the outcome for one input-derived key while preserving input order. Value is present for complete items; recovery fields explain retryable, unavailable, or failed items without failing unrelated work.

type BuildRepositoryDossierInput 

type BuildRepositoryDossierInput RepoInput

BuildRepositoryDossierInput selects a repository for durable dossier generation.

type CancelJobInput 

type CancelJobInput struct {
	IDs []string `json:"ids" jsonschema:"One to 100 durable job IDs"`
}

CancelJobInput selects durable jobs for bounded, persisted cancellation.

type CheckCollisionsInput 

type CheckCollisionsInput CheckDuplicatesInput

CheckCollisionsInput selects a hypothesis or opportunity for collision analysis.

type CheckDuplicatesInput 

type CheckDuplicatesInput struct {
	Target string `json:"target" jsonschema:"Target scope: hypothesis or opportunity"`
	ID     string `json:"id" jsonschema:"Hypothesis or opportunity ID"`
	Limit  int    `json:"limit,omitempty" jsonschema:"Maximum findings from 1 to 100"`
}

CheckDuplicatesInput selects a hypothesis or opportunity for duplicate analysis.

type CheckMergeConflictsInput added in v0.5.0 

type CheckMergeConflictsInput struct {
	Comparisons []MergeConflictInput `json:"comparisons" jsonschema:"One to 50 already-fetched revision comparisons"`
}

CheckMergeConflictsInput selects local revision comparisons.

type CheckMergeConflictsOutput added in v0.5.0 

type CheckMergeConflictsOutput struct {
	Status string                           `json:"status"`
	Items  []BatchItem[MergeConflictOutput] `json:"items"`
}

CheckMergeConflictsOutput preserves comparison order and isolates local Git failures to the affected comparison.

type CheckOutput 

type CheckOutput struct {
	Target         string         `json:"target"`
	ID             string         `json:"id"`
	Repo           string         `json:"repo,omitempty"`
	Query          string         `json:"query,omitempty"`
	Total          int            `json:"total"`
	Findings       []EvidenceItem `json:"findings,omitempty"`
	SourceRevision string         `json:"source_revision,omitempty"`
	Limit          int            `json:"limit"`
}

CheckOutput contains evidence-backed duplicate or collision findings.

type ClusterMemberOutput 

type ClusterMemberOutput struct {
	Kind     string  `json:"kind"`
	Owner    string  `json:"owner"`
	Repo     string  `json:"repo"`
	Number   int     `json:"number"`
	Title    string  `json:"title,omitempty"`
	State    string  `json:"state,omitempty"`
	Score    float64 `json:"score"`
	Reason   string  `json:"reason"`
	Included bool    `json:"included"`
}

ClusterMemberOutput describes one member of a duplicate cluster.

type ClusterOutput 

type ClusterOutput struct {
	StableID    string                `json:"stable_id"`
	State       string                `json:"state"`
	Canonical   ClusterMemberOutput   `json:"canonical"`
	MemberCount int                   `json:"member_count"`
	Members     []ClusterMemberOutput `json:"members,omitempty"`
}

ClusterOutput contains a stable duplicate cluster and its canonical member.

type CodeMatchOutput 

type CodeMatchOutput struct {
	ID       string `json:"id"`
	Repo     string `json:"repo"`
	Commit   string `json:"commit"`
	Path     string `json:"path"`
	Language string `json:"language,omitempty"`
	Snippet  string `json:"snippet"`
	Bytes    int    `json:"bytes"`
}

CodeMatchOutput identifies one stored code match.

type ContributionWorkflowResource 

type ContributionWorkflowResource struct {
	SchemaVersion string                `json:"schema_version"`
	OpportunityID string                `json:"opportunity_id"`
	Resources     []WorkflowResourceRef `json:"resources"`
	Prompts       []WorkflowPromptRef   `json:"prompts"`
	Safety        []string              `json:"safety"`
	NextSteps     []string              `json:"next_steps"`
}

ContributionWorkflowResource links safe local resources and prompts for one opportunity.

type CoverageOutput added in v0.6.0 

type CoverageOutput struct {
	Owner  string                `json:"owner"`
	Repo   string                `json:"repo"`
	Kind   string                `json:"kind,omitempty"`
	Number int                   `json:"number,omitempty"`
	AsOf   string                `json:"as_of"`
	Facets []FacetCoverageOutput `json:"facets"`
}

CoverageOutput reports all known coverage for one repository or thread.

type CoverageTarget added in v0.6.0 

type CoverageTarget struct {
	Owner  string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo   string `json:"repo" jsonschema:"GitHub repository name"`
	Kind   string `json:"kind,omitempty" jsonschema:"Optional thread kind: issue or pull_request"`
	Number int    `json:"number,omitempty" jsonschema:"Optional positive issue or pull request number"`
}

CoverageTarget selects repository-level coverage or, when kind and number are both present, coverage for one exact stored thread.

type CreateWorkspaceInput 

type CreateWorkspaceInput struct {
	InvestigationID string `json:"investigation_id" jsonschema:"Investigation ID"`
	Remote          string `json:"remote" jsonschema:"Git remote URL to clone"`
	BaseRef         string `json:"base_ref" jsonschema:"Base ref to resolve"`
	CandidateRef    string `json:"candidate_ref" jsonschema:"Candidate ref to resolve"`
	Name            string `json:"name" jsonschema:"Workspace name"`
}

CreateWorkspaceInput configures a durable managed-workspace creation job.

type DeepWikiInput added in v0.5.0 

type DeepWikiInput struct {
	Action         string   `json:"action" jsonschema:"structure, contents, or question"`
	Repository     string   `json:"repository,omitempty" jsonschema:"OWNER/REPO for structure or contents"`
	Repositories   []string `json:"repositories,omitempty" jsonschema:"One to 10 OWNER/REPO values for question"`
	Question       string   `json:"question,omitempty" jsonschema:"Focused cross-repository question"`
	MaxOutputBytes int      `json:"max_output_bytes,omitempty" jsonschema:"Maximum returned bytes from 1024 to 1048576"`
}

DeepWikiInput selects one bounded external derived-knowledge read. DeepWiki results are context, not authority for current GitHub state.

type DeepWikiOutput added in v0.5.0 

type DeepWikiOutput struct {
	Status       string   `json:"status"`
	Provider     string   `json:"provider"`
	Action       string   `json:"action"`
	Repositories []string `json:"repositories"`
	Question     string   `json:"question,omitempty"`
	Result       string   `json:"result,omitempty"`
	SourceURL    string   `json:"source_url,omitempty"`
	RetrievedAt  string   `json:"retrieved_at"`
	Provenance   string   `json:"provenance"`
	Truncated    bool     `json:"truncated"`
	Reason       string   `json:"reason,omitempty"`
	NextAction   string   `json:"next_action,omitempty"`
}

DeepWikiOutput labels provider prose as derived external content and reports provider-level unavailability without persisting the response.

type DefineValidationInput 

type DefineValidationInput struct {
	InvestigationID string   `json:"investigation_id" jsonschema:"Investigation ID"`
	Kind            string   `json:"kind" jsonschema:"Validation kind"`
	Command         string   `json:"command" jsonschema:"Shell-free command to execute"`
	WorkingDir      string   `json:"working_dir" jsonschema:"Working directory"`
	BaseWorkingDir  string   `json:"base_working_dir,omitempty" jsonschema:"Base workspace directory"`
	CandidateDir    string   `json:"candidate_dir,omitempty" jsonschema:"Candidate workspace directory"`
	Env             []string `json:"env,omitempty" jsonschema:"Allowed environment variable names"`
	Timeout         string   `json:"timeout,omitempty" jsonschema:"Positive Go duration; defaults to 30m"`
	MaxOutputBytes  int64    `json:"max_output_bytes,omitempty" jsonschema:"Maximum captured bytes per output stream; defaults to 65536"`
}

DefineValidationInput records a bounded validation command without executing it.

type DossierOutput 

type DossierOutput struct {
	Owner    string         `json:"owner"`
	Repo     string         `json:"repo"`
	AsOf     string         `json:"as_of,omitempty"`
	Sections map[string]any `json:"sections"`
}

DossierOutput contains a persisted repository dossier snapshot.

type DraftOutput 

type DraftOutput struct {
	OpportunityID string `json:"opportunity_id"`
	Kind          string `json:"kind"`
	Title         string `json:"title"`
	Body          string `json:"body"`
	RenderedAt    string `json:"rendered_at"`
}

DraftOutput contains a rendered contribution draft.

type EvidenceInput 

type EvidenceInput struct {
	InvestigationID string `json:"investigation_id,omitempty" jsonschema:"Filter by investigation ID"`
	OpportunityID   string `json:"opportunity_id,omitempty" jsonschema:"Filter by opportunity ID"`
	Relation        string `json:"relation,omitempty" jsonschema:"Optional relation filter: supporting, contradicting, inconclusive, stale, invalid"`
	Limit           int    `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
}

EvidenceInput filters and bounds stored evidence.

type EvidenceItem 

type EvidenceItem struct {
	ID               string                   `json:"id"`
	Type             string                   `json:"type"`
	Relation         string                   `json:"relation"`
	Description      string                   `json:"description"`
	SourceRefs       []SourceRef              `json:"source_refs,omitempty"`
	SourceProvenance []EvidenceSourceRevision `json:"source_provenance,omitempty"`
	Freshness        string                   `json:"freshness,omitempty"`
	FreshnessReason  string                   `json:"freshness_reason,omitempty"`
	CreatedAt        string                   `json:"created_at"`
}

EvidenceItem is the stable MCP representation of one evidence record.

type EvidenceOutput 

type EvidenceOutput struct {
	InvestigationID string         `json:"investigation_id,omitempty"`
	OpportunityID   string         `json:"opportunity_id,omitempty"`
	Total           int            `json:"total"`
	Evidence        []EvidenceItem `json:"evidence"`
}

EvidenceOutput contains bounded evidence matching a filter.

type EvidenceSourceRevision 

type EvidenceSourceRevision struct {
	Subject             EvidenceSourceSubject `json:"subject"`
	SourceUpdatedAt     string                `json:"source_updated_at,omitempty"`
	ObservationSequence int64                 `json:"observation_sequence"`
	ObservedAt          string                `json:"observed_at"`
}

EvidenceSourceRevision records the source order used by evidence.

type EvidenceSourceSubject 

type EvidenceSourceSubject struct {
	Kind       string `json:"kind"`
	Owner      string `json:"owner"`
	Repo       string `json:"repo"`
	ThreadKind string `json:"thread_kind,omitempty"`
	Number     int    `json:"number,omitempty"`
	Facet      string `json:"facet,omitempty"`
}

EvidenceSourceSubject identifies one independently refreshed corpus subject.

type ExplainMatchInput 

type ExplainMatchInput struct {
	Query  string `json:"query,omitempty" jsonschema:"Original search query"`
	Owner  string `json:"owner" jsonschema:"Repository owner"`
	Repo   string `json:"repo" jsonschema:"Repository name"`
	Kind   string `json:"kind,omitempty" jsonschema:"Match kind: repo, issue, pull_request, or code"`
	Number int    `json:"number,omitempty" jsonschema:"Thread number for issue or pull_request matches"`
	Path   string `json:"path,omitempty" jsonschema:"File path for code matches"`
	Commit string `json:"commit,omitempty" jsonschema:"Commit SHA for code matches"`
	Limit  int    `json:"limit,omitempty" jsonschema:"Maximum explanation facets from 1 to 100"`
}

ExplainMatchInput identifies an exact stored result and its original query.

type ExplainMatchOutput 

type ExplainMatchOutput struct {
	Query          string                `json:"query"`
	Kind           string                `json:"kind"`
	Owner          string                `json:"owner"`
	Repo           string                `json:"repo"`
	Number         int                   `json:"number,omitempty"`
	Path           string                `json:"path,omitempty"`
	Commit         string                `json:"commit,omitempty"`
	State          string                `json:"state,omitempty"`
	Title          string                `json:"title"`
	Snippet        string                `json:"snippet,omitempty"`
	MatchedFields  []string              `json:"matched_fields,omitempty"`
	Score          float64               `json:"score"`
	Reason         string                `json:"reason"`
	SourceRevision string                `json:"source_revision,omitempty"`
	Facets         []FacetCoverageOutput `json:"facets,omitempty"`
	AsOf           string                `json:"as_of,omitempty"`
}

ExplainMatchOutput reports the stored facts that contributed to a match score.

type FacetCoverageOutput 

type FacetCoverageOutput struct {
	Facet     string `json:"facet"`
	Complete  bool   `json:"complete"`
	Status    string `json:"status"`
	UpdatedAt string `json:"updated_at"`
}

FacetCoverageOutput reports completeness and freshness for one facet.

type FindClustersInput 

type FindClustersInput struct {
	Owner string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo  string `json:"repo" jsonschema:"GitHub repository name"`
	Limit int    `json:"limit,omitempty" jsonschema:"Maximum clusters from 1 to 100"`
}

FindClustersInput selects a repository and bounds duplicate clusters.

type FindClustersOutput 

type FindClustersOutput struct {
	Owner    string          `json:"owner"`
	Repo     string          `json:"repo"`
	Total    int             `json:"total"`
	Clusters []ClusterOutput `json:"clusters"`
}

FindClustersOutput contains duplicate clusters for a repository.

type FindNeighborsInput 

type FindNeighborsInput struct {
	Owner  string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo   string `json:"repo" jsonschema:"GitHub repository name"`
	Kind   string `json:"kind" jsonschema:"Thread kind: issue or pull_request"`
	Number int    `json:"number" jsonschema:"GitHub issue or pull request number"`
	Limit  int    `json:"limit,omitempty" jsonschema:"Maximum neighbors from 1 to 100"`
}

FindNeighborsInput selects a thread and bounds similar-thread results.

type FindNeighborsOutput 

type FindNeighborsOutput struct {
	Owner          string           `json:"owner"`
	Repo           string           `json:"repo"`
	Kind           string           `json:"kind"`
	Number         int              `json:"number"`
	SourceRevision string           `json:"source_revision"`
	Neighbors      []NeighborOutput `json:"neighbors"`
}

FindNeighborsOutput contains deterministic neighbors for a stored thread.

type FindPortfolioOverlapsInput added in v0.6.0 

type FindPortfolioOverlapsInput struct {
	Candidates   []PortfolioSubjectInput `json:"candidates" jsonschema:"One to 50 local candidate subjects"`
	PullRequests []ThreadRef             `json:"pull_requests" jsonschema:"One to 100 exact authored pull requests"`
}

FindPortfolioOverlapsInput compares candidates with exact stored authored PRs.

type FindPortfolioOverlapsOutput added in v0.6.0 

type FindPortfolioOverlapsOutput struct {
	Status string                              `json:"status"`
	Items  []BatchItem[PortfolioOverlapOutput] `json:"items"`
}

FindPortfolioOverlapsOutput preserves candidate input order.

type FindPrecedentsInput added in v0.5.0 

type FindPrecedentsInput struct {
	Threads []ThreadRef `json:"threads" jsonschema:"One to 20 source threads"`
	Limit   int         `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
}

FindPrecedentsInput selects source threads for offline analogue discovery.

type FindPrecedentsOutput added in v0.5.0 

type FindPrecedentsOutput struct {
	Status string                         `json:"status"`
	Items  []BatchItem[[]PrecedentOutput] `json:"items"`
	Total  int                            `json:"total"`
}

FindPrecedentsOutput returns stored closed or merged analogues for each source thread; it does not perform a network read.

type GetCoverageInput 

type GetCoverageInput struct {
	Targets []CoverageTarget `json:"targets" jsonschema:"One to 100 repository or exact-thread targets"`
}

GetCoverageInput selects bounded repository or thread facet coverage reads.

type GetCoverageOutput 

type GetCoverageOutput struct {
	Status string                      `json:"status"`
	Items  []BatchItem[CoverageOutput] `json:"items"`
}

GetCoverageOutput preserves target order and isolates missing or invalid targets without failing unrelated coverage reads.

type GetJobInput 

type GetJobInput struct {
	ID string `json:"id" jsonschema:"Durable job ID"`
}

GetJobInput selects a durable job by opaque ID.

type GetJobOutput 

type GetJobOutput struct {
	ID                    string `json:"id"`
	Kind                  string `json:"kind"`
	Status                string `json:"status"`
	Request               any    `json:"request,omitempty"`
	Result                any    `json:"result,omitempty"`
	Error                 string `json:"error,omitempty"`
	Phase                 string `json:"phase,omitempty"`
	CompletedItems        int    `json:"completed_items"`
	TotalItems            int    `json:"total_items"`
	ProgressPercent       int    `json:"progress_percent"`
	RetryAfterMS          int    `json:"retry_after_ms,omitempty"`
	CreatedAt             string `json:"created_at"`
	StartedAt             string `json:"started_at,omitempty"`
	CompletedAt           string `json:"completed_at,omitempty"`
	CancelledAt           string `json:"cancelled_at,omitempty"`
	CancellationRequested bool   `json:"cancellation_requested"`
}

GetJobOutput reports durable state and structured progress for a job.

type GetJobsInput added in v0.5.0 

type GetJobsInput struct {
	IDs []string `json:"ids" jsonschema:"One to 100 durable job IDs"`
}

GetJobsInput selects durable jobs for a bounded status read.

type GetJobsOutput added in v0.5.0 

type GetJobsOutput struct {
	Status string                    `json:"status"`
	Items  []BatchItem[GetJobOutput] `json:"items"`
}

GetJobsOutput reports multiple durable jobs in requested order so callers can poll concurrent work with one MCP round trip.

type GetRepositoriesInput added in v0.5.0 

type GetRepositoriesInput struct {
	Repositories []RepositoryRef `json:"repositories" jsonschema:"One to 100 repository identities"`
}

GetRepositoriesInput selects repositories for a bounded corpus read.

type GetRepositoriesOutput added in v0.5.0 

type GetRepositoriesOutput struct {
	Status string                             `json:"status"`
	Items  []BatchItem[TypedRepositoryOutput] `json:"items"`
}

GetRepositoriesOutput preserves repository input order and represents unobserved metadata with nullable facts instead of false zero values.

type GetRepositoryDossierInput 

type GetRepositoryDossierInput RepoInput

GetRepositoryDossierInput selects a persisted repository dossier.

type GetThreadsInput added in v0.5.0 

type GetThreadsInput struct {
	Threads []ThreadRef `json:"threads" jsonschema:"One to 100 exact thread identities"`
	View    string      `json:"view,omitempty" jsonschema:"compact or full; compact omits bodies"`
}

GetThreadsInput selects exact threads and the desired response view.

type GetThreadsOutput added in v0.5.0 

type GetThreadsOutput struct {
	Status string                    `json:"status"`
	Items  []BatchItem[ThreadOutput] `json:"items"`
}

GetThreadsOutput preserves exact-thread input order and item-level failures.

type HydrateThreadsInput added in v0.5.0 

type HydrateThreadsInput struct {
	Threads  []ThreadRef `json:"threads" jsonschema:"One to 100 exact threads"`
	Facets   []string    `json:"facets" jsonschema:"One or more explicit child facets"`
	MaxPages int         `json:"max_pages,omitempty" jsonschema:"Maximum pages per facet from 1 to 100"`
}

HydrateThreadsInput requests explicit child facets for already selected threads. Facets must be non-empty to prevent accidental broad hydration.

type HypothesisOutput 

type HypothesisOutput struct {
	ID                 string      `json:"id"`
	InvestigationID    string      `json:"investigation_id"`
	Title              string      `json:"title"`
	Description        string      `json:"description"`
	Category           string      `json:"category"`
	ExpectedBehavior   string      `json:"expected_behavior,omitempty"`
	ObservedBehavior   string      `json:"observed_behavior,omitempty"`
	PotentialImpact    string      `json:"potential_impact,omitempty"`
	OpenQuestions      []string    `json:"open_questions,omitempty"`
	AffectedComponents []string    `json:"affected_components,omitempty"`
	SourceRefs         []SourceRef `json:"source_refs,omitempty"`
	Status             string      `json:"status"`
	CreatedAt          string      `json:"created_at"`
	UpdatedAt          string      `json:"updated_at"`
}

HypothesisOutput is the stable MCP representation of a hypothesis.

type HypothesisSummary 

type HypothesisSummary struct {
	ID          string `json:"id"`
	Title       string `json:"title"`
	Category    string `json:"category"`
	Status      string `json:"status"`
	Description string `json:"description,omitempty"`
}

HypothesisSummary is the compact hypothesis representation nested in an investigation.

type IndexRepositoriesInput added in v0.5.0 

type IndexRepositoriesInput struct {
	Repositories []IndexRepositoryInput `json:"repositories" jsonschema:"One to 10 repositories to acquire and index"`
}

IndexRepositoriesInput selects repositories for bounded asynchronous indexing.

type IndexRepositoryInput added in v0.5.0 

type IndexRepositoryInput struct {
	Owner  string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo   string `json:"repo" jsonschema:"GitHub repository name"`
	Remote string `json:"remote,omitempty" jsonschema:"Optional explicit credential-free Git remote"`
}

IndexRepositoryInput identifies one repository to acquire and index.

type InvestigationInput 

type InvestigationInput struct {
	ID              string `json:"id" jsonschema:"Investigation ID"`
	HypothesisLimit int    `json:"hypothesis_limit,omitempty" jsonschema:"Maximum hypotheses from 1 to 100"`
}

InvestigationInput selects an investigation and bounds nested hypotheses.

type InvestigationOutput 

type InvestigationOutput struct {
	ID              string              `json:"id"`
	Owner           string              `json:"owner"`
	Repo            string              `json:"repo"`
	CommitSHA       string              `json:"commit_sha,omitempty"`
	Lens            string              `json:"lens,omitempty"`
	Status          string              `json:"status"`
	CreatedAt       string              `json:"created_at"`
	UpdatedAt       string              `json:"updated_at"`
	HypothesisTotal int                 `json:"hypothesis_total"`
	Hypotheses      []HypothesisSummary `json:"hypotheses,omitempty"`
}

InvestigationOutput is the stable MCP representation of an investigation.

type JobReference 

type JobReference struct {
	ID               string            `json:"id"`
	Ref              string            `json:"ref"`
	Kind             string            `json:"kind"`
	Status           string            `json:"status"`
	Message          string            `json:"message"`
	PollAfterMS      int               `json:"poll_after_ms,omitempty"`
	SuggestedActions []SuggestedAction `json:"suggested_actions,omitempty"`
}

JobReference is returned by long-running tools that submit durable jobs.

type LensInput 

type LensInput struct {
	Name string `json:"name" jsonschema:"Lens name"`
}

LensInput selects a saved lens by name.

type LensOutput 

type LensOutput struct {
	Name       string          `json:"name"`
	Definition lens.Definition `json:"definition"`
	CreatedAt  string          `json:"created_at"`
	UpdatedAt  string          `json:"updated_at"`
}

LensOutput contains a saved lens definition and timestamps.

type LinkPullRequestInput added in v0.6.0 

type LinkPullRequestInput struct {
	PullRequest   ThreadRef `json:"pull_request" jsonschema:"Exact stored pull request to link"`
	OpportunityID string    `json:"opportunity_id,omitempty" jsonschema:"Optional local opportunity ID"`
	WorkspaceID   string    `json:"workspace_id,omitempty" jsonschema:"Optional managed workspace ID"`
}

LinkPullRequestInput explicitly associates a stored PR with local workflow state.

type LinkPullRequestOutput added in v0.6.0 

type LinkPullRequestOutput struct {
	ID                  int64  `json:"id"`
	PullRequestThreadID int64  `json:"pull_request_thread_id"`
	OpportunityID       string `json:"opportunity_id,omitempty"`
	WorkspaceID         string `json:"workspace_id,omitempty"`
	CreatedAt           string `json:"created_at"`
}

LinkPullRequestOutput reports the idempotently stored local relationship.

type ListOpportunitiesInput 

type ListOpportunitiesInput struct {
	InvestigationID string `json:"investigation_id" jsonschema:"Investigation ID"`
	Limit           int    `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
}

ListOpportunitiesInput selects and bounds opportunities for an investigation.

type ListOpportunitiesOutput 

type ListOpportunitiesOutput struct {
	Opportunities []OpportunitySummary `json:"opportunities"`
	Total         int                  `json:"total"`
}

ListOpportunitiesOutput contains bounded opportunities for an investigation.

type ListPullRequestPortfolioInput added in v0.5.0 

type ListPullRequestPortfolioInput struct {
	Author string `json:"author,omitempty" jsonschema:"Optional authored GitHub login"`
	State  string `json:"state,omitempty" jsonschema:"open, closed, or all"`
	Limit  int    `json:"limit,omitempty" jsonschema:"Maximum pull requests from 1 to 100"`
}

ListPullRequestPortfolioInput filters and bounds the stored pull-request portfolio.

type ListPullRequestPortfolioOutput added in v0.5.0 

type ListPullRequestPortfolioOutput struct {
	Status       string                     `json:"status"`
	RuleVersion  string                     `json:"rule_version"`
	GeneratedAt  string                     `json:"generated_at"`
	PullRequests []PullRequestPortfolioItem `json:"pull_requests"`
	Total        int                        `json:"total"`
}

ListPullRequestPortfolioOutput contains a deterministic portfolio projection.

type MergeConflictInput added in v0.5.0 

type MergeConflictInput struct {
	WorkspaceID string `json:"workspace_id"`
	BaseOID     string `json:"base_oid"`
	HeadOID     string `json:"head_oid"`
}

MergeConflictInput names two already-fetched revisions in a managed workspace.

type MergeConflictOutput added in v0.5.0 

type MergeConflictOutput struct {
	WorkspaceID string `json:"workspace_id"`
	BaseOID     string `json:"base_oid"`
	HeadOID     string `json:"head_oid"`
	MergeBase   string `json:"merge_base,omitempty"`
	Conflicted  bool   `json:"conflicted"`
	Summary     string `json:"summary"`
}

MergeConflictOutput reports the result of one local revision comparison.

type NeighborOutput 

type NeighborOutput struct {
	Kind   string  `json:"kind"`
	Owner  string  `json:"owner"`
	Repo   string  `json:"repo"`
	Number int     `json:"number"`
	Title  string  `json:"title"`
	State  string  `json:"state"`
	Score  float64 `json:"score"`
	Reason string  `json:"reason"`
}

NeighborOutput describes one similar stored thread and its score.

type NeighborReader 

type NeighborReader interface {
	FindNeighbors(context.Context, FindNeighborsInput) (FindNeighborsOutput, error)
}

NeighborReader is the optional local nearest-thread query capability.

type Operator 

type Operator interface {
	BuildRepositoryDossier(context.Context, BuildRepositoryDossierInput) (JobReference, error)
	StartInvestigation(context.Context, StartInvestigationInput) (InvestigationOutput, error)
	RecordHypothesis(context.Context, RecordHypothesisInput) (HypothesisOutput, error)
	CheckDuplicates(context.Context, CheckDuplicatesInput) (CheckOutput, error)
	CheckCollisions(context.Context, CheckCollisionsInput) (CheckOutput, error)
	PromoteOpportunity(context.Context, PromoteOpportunityInput) (OpportunityOutput, error)
	CreateWorkspace(context.Context, CreateWorkspaceInput) (JobReference, error)
	DefineValidation(context.Context, DefineValidationInput) (ValidationOutput, error)
	RunValidation(context.Context, RunValidationInput) (JobReference, error)
	PrepareContribution(context.Context, PrepareContributionInput) (DraftOutput, error)
	CancelJobs(context.Context, CancelJobInput) (GetJobsOutput, error)
}

Operator is the optional explicit network-read/local-write capability.

type OpportunityCandidateOutput added in v0.5.0 

type OpportunityCandidateOutput struct {
	Rank               int      `json:"rank"`
	Ref                string   `json:"ref"`
	Repo               string   `json:"repo"`
	Number             int      `json:"number"`
	Title              string   `json:"title"`
	URL                string   `json:"url"`
	Score              int      `json:"score"`
	Eligibility        string   `json:"eligibility"`
	Confidence         string   `json:"confidence"`
	PositiveSignals    []string `json:"positive_signals,omitempty"`
	Risks              []string `json:"risks,omitempty"`
	Blockers           []string `json:"blockers,omitempty"`
	Unknowns           []string `json:"unknowns,omitempty"`
	LinkedPullRequests []int    `json:"linked_pull_requests,omitempty"`
	SourceUpdatedAt    string   `json:"source_updated_at,omitempty"`
}

OpportunityCandidateOutput describes one ranked contribution candidate.

type OpportunityInput 

type OpportunityInput struct {
	ID            string `json:"id" jsonschema:"Opportunity ID"`
	EvidenceLimit int    `json:"evidence_limit,omitempty" jsonschema:"Maximum evidence IDs from 1 to 100"`
}

OpportunityInput selects an opportunity and bounds nested evidence.

type OpportunityOutput 

type OpportunityOutput struct {
	ID                  string      `json:"id"`
	InvestigationID     string      `json:"investigation_id"`
	HypothesisID        string      `json:"hypothesis_id,omitempty"`
	Title               string      `json:"title"`
	ProblemStatement    string      `json:"problem_statement"`
	Category            string      `json:"category"`
	Scope               string      `json:"scope"`
	Impact              string      `json:"impact"`
	Confidence          float64     `json:"confidence"`
	ExpectedEffort      string      `json:"expected_effort,omitempty"`
	Dependencies        []string    `json:"dependencies,omitempty"`
	CollisionStatus     string      `json:"collision_status"`
	MaintainerAlignment string      `json:"maintainer_alignment,omitempty"`
	SourceRefs          []SourceRef `json:"source_refs,omitempty"`
	EvidenceTotal       int         `json:"evidence_total"`
	EvidenceIDs         []string    `json:"evidence_ids,omitempty"`
	Status              string      `json:"status"`
	CreatedAt           string      `json:"created_at"`
	UpdatedAt           string      `json:"updated_at"`
}

OpportunityOutput is the stable MCP representation of a contribution opportunity.

type OpportunitySummary 

type OpportunitySummary struct {
	ID              string  `json:"id"`
	InvestigationID string  `json:"investigation_id"`
	Title           string  `json:"title"`
	Category        string  `json:"category"`
	Status          string  `json:"status"`
	Confidence      float64 `json:"confidence"`
	CollisionStatus string  `json:"collision_status"`
	CreatedAt       string  `json:"created_at"`
	UpdatedAt       string  `json:"updated_at"`
}

OpportunitySummary is the compact opportunity representation used in lists.

type PortfolioOperator added in v0.6.0 

type PortfolioOperator interface {
	LinkPullRequest(context.Context, LinkPullRequestInput) (LinkPullRequestOutput, error)
}

PortfolioOperator owns explicit local links between observed pull requests and contribution workflow state. It never mutates GitHub.

type PortfolioOverlapEvidenceOutput added in v0.6.0 

type PortfolioOverlapEvidenceOutput struct {
	Kind       string   `json:"kind"`
	Value      string   `json:"value"`
	Score      float64  `json:"score,omitempty"`
	SourceRefs []string `json:"source_refs"`
}

PortfolioOverlapEvidenceOutput is one exact observed overlap reason.

type PortfolioOverlapMatchOutput added in v0.6.0 

type PortfolioOverlapMatchOutput struct {
	PullRequestThreadID int64                            `json:"pull_request_thread_id"`
	Evidence            []PortfolioOverlapEvidenceOutput `json:"evidence"`
}

PortfolioOverlapMatchOutput associates overlap evidence with one authored PR.

type PortfolioOverlapOutput added in v0.6.0 

type PortfolioOverlapOutput struct {
	Candidate PortfolioSubjectInput         `json:"candidate"`
	Status    string                        `json:"status"`
	Coverage  map[string]string             `json:"coverage"`
	Matches   []PortfolioOverlapMatchOutput `json:"matches"`
}

PortfolioOverlapOutput preserves explicit coverage and never infers no overlap.

type PortfolioSubjectInput added in v0.6.0 

type PortfolioSubjectInput struct {
	Kind string `json:"kind" jsonschema:"Candidate kind: opportunity, workspace, or pull_request"`
	Ref  string `json:"ref" jsonschema:"Local candidate ID or corpus pull-request thread ID"`
}

PortfolioSubjectInput identifies local candidate state for offline overlap analysis.

type PrecedentOutput added in v0.5.0 

type PrecedentOutput struct {
	Source      string   `json:"source"`
	Ref         string   `json:"ref"`
	Kind        string   `json:"kind"`
	State       string   `json:"state"`
	StateReason string   `json:"state_reason,omitempty"`
	Title       string   `json:"title"`
	Score       float64  `json:"score"`
	Reasons     []string `json:"reasons"`
	ClosedAt    string   `json:"closed_at,omitempty"`
	MergedAt    string   `json:"merged_at,omitempty"`
}

PrecedentOutput describes one stored thread analogous to a source thread.

type PrepareContributionInput 

type PrepareContributionInput struct {
	OpportunityID string `json:"opportunity_id" jsonschema:"Opportunity ID"`
	Kind          string `json:"kind" jsonschema:"Contribution kind: issue or pull_request"`
	WorkspaceID   string `json:"workspace_id,omitempty" jsonschema:"Workspace ID for pull_request drafts"`
	Approach      string `json:"approach,omitempty" jsonschema:"Approach summary for pull requests"`
	Changes       string `json:"changes,omitempty" jsonschema:"Changes summary for pull requests"`
	Compatibility string `json:"compatibility,omitempty" jsonschema:"Compatibility notes for pull requests"`
	Limitations   string `json:"limitations,omitempty" jsonschema:"Limitations for pull requests"`
	LinkedIssue   string `json:"linked_issue,omitempty" jsonschema:"Linked issue for pull requests"`
	Guidance      string `json:"guidance,omitempty" jsonschema:"Optional guidance to include"`
	Success       string `json:"success,omitempty" jsonschema:"Success criteria for issue drafts"`
}

PrepareContributionInput renders a local issue or pull-request draft.

type PromoteOpportunityInput 

type PromoteOpportunityInput struct {
	HypothesisID        string      `json:"hypothesis_id" jsonschema:"Hypothesis ID to promote"`
	ProblemStatement    string      `json:"problem_statement" jsonschema:"Problem statement"`
	Scope               string      `json:"scope" jsonschema:"Scope of the opportunity"`
	Impact              string      `json:"impact" jsonschema:"Impact of the opportunity"`
	ExpectedEffort      string      `json:"expected_effort" jsonschema:"Expected effort"`
	Confidence          float64     `json:"confidence" jsonschema:"Confidence from 0.0 to 1.0"`
	Dependencies        []string    `json:"dependencies,omitempty" jsonschema:"Dependencies"`
	MaintainerAlignment string      `json:"maintainer_alignment,omitempty" jsonschema:"Maintainer alignment note"`
	SourceRefs          []SourceRef `json:"source_refs,omitempty" jsonschema:"Source references"`
}

PromoteOpportunityInput converts a hypothesis into a scoped opportunity.

type PullRequestPortfolioItem added in v0.5.0 

type PullRequestPortfolioItem struct {
	Ref                     string                `json:"ref"`
	Owner                   string                `json:"owner"`
	Repo                    string                `json:"repo"`
	Number                  int                   `json:"number"`
	Title                   string                `json:"title"`
	State                   string                `json:"state"`
	Author                  string                `json:"author"`
	Draft                   bool                  `json:"draft"`
	Attention               string                `json:"attention"`
	Reasons                 []string              `json:"reasons"`
	Mergeable               *bool                 `json:"mergeable,omitempty"`
	MergeStateStatus        string                `json:"merge_state_status,omitempty"`
	HeadRef                 string                `json:"head_ref,omitempty"`
	HeadSHA                 string                `json:"head_sha,omitempty"`
	BaseRef                 string                `json:"base_ref,omitempty"`
	BaseSHA                 string                `json:"base_sha,omitempty"`
	ReviewDecision          string                `json:"review_decision,omitempty"`
	ChecksStatus            string                `json:"checks_status,omitempty"`
	ChecksTotal             int                   `json:"checks_total,omitempty"`
	UnresolvedReviewThreads *int                  `json:"unresolved_review_threads,omitempty"`
	MergeQueueState         string                `json:"merge_queue_state,omitempty"`
	MergeQueuePosition      int                   `json:"merge_queue_position,omitempty"`
	ClosingIssues           []string              `json:"closing_issues,omitempty"`
	ChangedFiles            []string              `json:"changed_files,omitempty"`
	StatusCoverage          string                `json:"status_coverage"`
	Facets                  []FacetCoverageOutput `json:"facets"`
	SourceUpdatedAt         string                `json:"source_updated_at"`
	StatusObservedAt        string                `json:"status_observed_at,omitempty"`
}

PullRequestPortfolioItem contains source-backed PR facts and a deterministic portfolio.v1 attention classification. Missing status facets remain explicit in StatusCoverage and Reasons.

type RankOpportunitiesInput added in v0.5.0 

type RankOpportunitiesInput struct {
	Repositories            []RepositoryRef `json:"repositories" jsonschema:"One to 50 stored repositories"`
	Limit                   int             `json:"limit,omitempty" jsonschema:"Maximum total candidates from 1 to 100"`
	MaxResultsPerRepository int             `json:"max_results_per_repository,omitempty" jsonschema:"Maximum candidates per repository from 1 to 100"`
}

RankOpportunitiesInput bounds ranking across stored repositories.

type RankOpportunitiesOutput added in v0.5.0 

type RankOpportunitiesOutput struct {
	Status       string                                          `json:"status"`
	Candidates   []OpportunityCandidateOutput                    `json:"candidates"`
	Repositories []BatchItem[RepositoryOpportunitySummaryOutput] `json:"repositories"`
	GeneratedAt  string                                          `json:"generated_at"`
}

RankOpportunitiesOutput combines deterministic cross-repository ranking with per-repository coverage or availability results.

type Reader 

type Reader interface {
	Search(context.Context, SearchInput) (SearchOutput, error)
	SearchRepositories(context.Context, SearchRepositoriesInput) (SearchRepositoriesOutput, error)
	Repository(context.Context, RepoInput) (RepositoryOutput, error)
	Thread(context.Context, ThreadInput) (ThreadOutput, error)
	ThreadByNumber(context.Context, ThreadByNumberInput) (ThreadOutput, error)
	Dossier(context.Context, RepoInput) (DossierOutput, error)
	SearchCode(context.Context, SearchCodeInput) (SearchCodeOutput, error)
	ExplainMatch(context.Context, ExplainMatchInput) (ExplainMatchOutput, error)
	GetJob(context.Context, GetJobInput) (GetJobOutput, error)
	Investigation(context.Context, InvestigationInput) (InvestigationOutput, error)
	ListOpportunities(context.Context, ListOpportunitiesInput) (ListOpportunitiesOutput, error)
	Opportunity(context.Context, OpportunityInput) (OpportunityOutput, error)
	Evidence(context.Context, EvidenceInput) (EvidenceOutput, error)
	Readiness(context.Context, ReadinessInput) (ReadinessOutput, error)
	FindClusters(context.Context, FindClustersInput) (FindClustersOutput, error)
	GetCoverage(context.Context, GetCoverageInput) (GetCoverageOutput, error)
	Lens(context.Context, LensInput) (LensOutput, error)
}

Reader is the local, read-only application boundary exposed through MCP. Implementations must not perform network access.

type ReadinessCheck 

type ReadinessCheck struct {
	CheckID      string   `json:"check_id"`
	RuleID       string   `json:"rule_id"`
	RuleVersion  string   `json:"rule_version"`
	Status       string   `json:"status"`
	Summary      string   `json:"summary"`
	EvidenceRefs []string `json:"evidence_refs,omitempty"`
	Remediation  string   `json:"remediation,omitempty"`
	EvaluatedAt  string   `json:"evaluated_at"`
}

ReadinessCheck is one explainable readiness rule result.

type ReadinessInput 

type ReadinessInput struct {
	OpportunityID string `json:"opportunity_id" jsonschema:"Opportunity ID"`
}

ReadinessInput selects a contribution opportunity readiness report.

type ReadinessOutput 

type ReadinessOutput struct {
	OpportunityID  string           `json:"opportunity_id"`
	RuleSetVersion string           `json:"rule_set_version"`
	Status         string           `json:"status"`
	EvaluatedAt    string           `json:"evaluated_at"`
	Checks         []ReadinessCheck `json:"checks"`
}

ReadinessOutput is the stable MCP representation of one readiness report.

type RecordHypothesisInput 

type RecordHypothesisInput struct {
	InvestigationID    string      `json:"investigation_id" jsonschema:"Investigation ID"`
	Title              string      `json:"title" jsonschema:"Hypothesis title"`
	Description        string      `json:"description" jsonschema:"Hypothesis description"`
	Category           string      `json:"category" jsonschema:"Category such as bug, performance, or documentation"`
	ExpectedBehavior   string      `json:"expected_behavior,omitempty" jsonschema:"Expected behavior"`
	ObservedBehavior   string      `json:"observed_behavior,omitempty" jsonschema:"Observed behavior"`
	PotentialImpact    string      `json:"potential_impact,omitempty" jsonschema:"Potential impact"`
	OpenQuestions      []string    `json:"open_questions,omitempty" jsonschema:"Open questions"`
	AffectedComponents []string    `json:"affected_components,omitempty" jsonschema:"Affected components"`
	SourceRefs         []SourceRef `json:"source_refs,omitempty" jsonschema:"Source references"`
}

RecordHypothesisInput records a structured hypothesis and its provenance.

type RepoInput 

type RepoInput struct {
	Owner string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo  string `json:"repo" jsonschema:"GitHub repository name"`
}

RepoInput identifies a repository for an MCP operation.

type RepositoryMetadataOutput added in v0.5.0 

type RepositoryMetadataOutput struct {
	Status          string `json:"status"`
	ObservedAt      string `json:"observed_at,omitempty"`
	SourceUpdatedAt string `json:"source_updated_at,omitempty"`
	NextAction      string `json:"next_action,omitempty"`
}

RepositoryMetadataOutput describes the coverage of repository metadata.

type RepositoryOpportunitySummaryOutput added in v0.5.0 

type RepositoryOpportunitySummaryOutput struct {
	Repo            string `json:"repo"`
	TotalOpenIssues int    `json:"total_open_issues"`
	Considered      int    `json:"considered"`
}

RepositoryOpportunitySummaryOutput reports ranking coverage for one repository.

type RepositoryOutput 

type RepositoryOutput struct {
	Owner     string         `json:"owner"`
	Repo      string         `json:"repo"`
	UpdatedAt string         `json:"updated_at,omitempty"`
	Fields    map[string]any `json:"fields,omitempty"`
}

RepositoryOutput is the stable MCP representation of a repository.

type RepositoryRef added in v0.5.0 

type RepositoryRef struct {
	Owner string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo  string `json:"repo" jsonschema:"GitHub repository name"`
}

RepositoryRef identifies one GitHub repository without implying that it has been fetched or indexed locally.

type RepositorySearchMatch added in v0.7.0 

type RepositorySearchMatch struct {
	Ref           string                   `json:"ref"`
	Owner         string                   `json:"owner"`
	Repo          string                   `json:"repo"`
	Description   *string                  `json:"description,omitempty"`
	Language      *string                  `json:"language,omitempty"`
	Stars         *int                     `json:"stars,omitempty"`
	PushedAt      string                   `json:"pushed_at,omitempty"`
	Metadata      RepositoryMetadataOutput `json:"metadata"`
	DefaultBranch *string                  `json:"default_branch,omitempty"`
	License       *string                  `json:"license,omitempty"`
	Topics        []string                 `json:"topics,omitempty"`
	Watchers      *int                     `json:"watchers,omitempty"`
	Forks         *int                     `json:"forks,omitempty"`
	OpenIssues    *int                     `json:"open_issues,omitempty"`
	Archived      *bool                    `json:"archived,omitempty"`
	Fork          *bool                    `json:"fork,omitempty"`
}

RepositorySearchMatch is a token-bounded live repository search result.

type RunValidationInput 

type RunValidationInput struct {
	ID      string `json:"id" jsonschema:"Validation definition ID"`
	Kind    string `json:"kind" jsonschema:"Run kind: base or candidate"`
	Execute bool   `json:"execute" jsonschema:"Must be true to authorize host execution"`
}

RunValidationInput selects a validation definition and explicitly authorizes execution.

type ScalableOperator added in v0.5.0 

type ScalableOperator interface {
	SearchGitHubRepositories(context.Context, SearchGitHubRepositoriesInput) (SearchGitHubRepositoriesOutput, error)
	SyncRepositoryMetadata(context.Context, SyncRepositoryMetadataInput) (JobReference, error)
	SyncThreads(context.Context, SyncThreadsInput) (JobReference, error)
	HydrateThreads(context.Context, HydrateThreadsInput) (JobReference, error)
	GetAuthenticatedIdentity(context.Context) (AuthenticatedIdentityOutput, error)
	SyncAuthoredPullRequests(context.Context, SyncAuthoredPullRequestsInput) (JobReference, error)
	SyncPullRequestStatus(context.Context, SyncPullRequestStatusInput) (JobReference, error)
	IndexRepositories(context.Context, IndexRepositoriesInput) (JobReference, error)
	CheckMergeConflicts(context.Context, CheckMergeConflictsInput) (CheckMergeConflictsOutput, error)
	DeepWiki(context.Context, DeepWikiInput) (DeepWikiOutput, error)
}

ScalableOperator exposes bounded external reads without combining unrelated facets or workflow mutations.

type ScalableReader added in v0.5.0 

type ScalableReader interface {
	GetRepositories(context.Context, GetRepositoriesInput) (GetRepositoriesOutput, error)
	GetThreads(context.Context, GetThreadsInput) (GetThreadsOutput, error)
	RankOpportunities(context.Context, RankOpportunitiesInput) (RankOpportunitiesOutput, error)
	FindPrecedents(context.Context, FindPrecedentsInput) (FindPrecedentsOutput, error)
	GetJobs(context.Context, GetJobsInput) (GetJobsOutput, error)
	ListPullRequestPortfolio(context.Context, ListPullRequestPortfolioInput) (ListPullRequestPortfolioOutput, error)
	FindPortfolioOverlaps(context.Context, FindPortfolioOverlapsInput) (FindPortfolioOverlapsOutput, error)
}

ScalableReader exposes bounded vectorized corpus reads. Implementations must remain offline and preserve input order for non-ranked results.

type SearchCodeInput 

type SearchCodeInput struct {
	Query  string `json:"query" jsonschema:"Code search query"`
	Owner  string `json:"owner,omitempty" jsonschema:"Optional repository owner"`
	Repo   string `json:"repo,omitempty" jsonschema:"Optional repository name"`
	Limit  int    `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
	Cursor string `json:"cursor,omitempty" jsonschema:"Opaque cursor returned by the previous page"`
}

SearchCodeInput describes an offline code search page.

type SearchCodeOutput 

type SearchCodeOutput struct {
	Query      string            `json:"query"`
	Total      int               `json:"total"`
	Matches    []CodeMatchOutput `json:"matches"`
	NextCursor string            `json:"next_cursor,omitempty"`
}

SearchCodeOutput contains one page of offline code matches.

type SearchGitHubRepositoriesInput added in v0.5.0 

type SearchGitHubRepositoriesInput struct {
	Query          string   `json:"query,omitempty" jsonschema:"Deprecated raw GitHub query"`
	RawQuery       string   `json:"raw_query,omitempty" jsonschema:"Advanced raw GitHub query; exclusive with filters"`
	Text           string   `json:"text,omitempty" jsonschema:"Text to match"`
	MatchFields    []string `json:"match_fields,omitempty" jsonschema:"Text fields: name, description, or readme"`
	Topics         []string `json:"topics,omitempty" jsonschema:"Topics that must all match"`
	Language       string   `json:"language,omitempty" jsonschema:"Primary language"`
	StarsMin       int      `json:"stars_min,omitempty" jsonschema:"Minimum stargazer count"`
	StarsMax       int      `json:"stars_max,omitempty" jsonschema:"Maximum stargazer count"`
	CreatedAfter   string   `json:"created_after,omitempty" jsonschema:"Created on or after YYYY-MM-DD"`
	CreatedBefore  string   `json:"created_before,omitempty" jsonschema:"Created on or before YYYY-MM-DD"`
	PushedAfter    string   `json:"pushed_after,omitempty" jsonschema:"Pushed on or after YYYY-MM-DD"`
	PushedBefore   string   `json:"pushed_before,omitempty" jsonschema:"Pushed on or before YYYY-MM-DD"`
	Archived       *bool    `json:"archived,omitempty" jsonschema:"Archived state"`
	Fork           *bool    `json:"fork,omitempty" jsonschema:"Fork state"`
	Sort           string   `json:"sort,omitempty" jsonschema:"Optional GitHub sort: stars, forks, help-wanted-issues, or updated"`
	Order          string   `json:"order,omitempty" jsonschema:"Sort order: asc or desc"`
	Limit          int      `json:"limit,omitempty" jsonschema:"Results per page from 1 to 100"`
	Page           int      `json:"page,omitempty" jsonschema:"Result page within GitHub's 1,000-result cap"`
	ResponseFormat string   `json:"response_format,omitempty" jsonschema:"concise or detailed"`
}

SearchGitHubRepositoriesInput defines one bounded live GitHub search.

type SearchGitHubRepositoriesOutput added in v0.5.0 

type SearchGitHubRepositoriesOutput struct {
	Status           string                             `json:"status"`
	Query            string                             `json:"query"`
	Interpretation   string                             `json:"interpretation"`
	ResponseFormat   string                             `json:"response_format"`
	Page             int                                `json:"page"`
	NextPage         int                                `json:"next_page,omitempty"`
	Total            int                                `json:"total"`
	Incomplete       bool                               `json:"incomplete"`
	Items            []BatchItem[RepositorySearchMatch] `json:"items"`
	Warnings         []SearchWarning                    `json:"warnings,omitempty"`
	SuggestedActions []SuggestedAction                  `json:"suggested_actions,omitempty"`
}

SearchGitHubRepositoriesOutput contains search results and completeness metadata.

type SearchInput 

type SearchInput struct {
	Query        string   `json:"query" jsonschema:"Full-text query"`
	Owner        string   `json:"owner,omitempty" jsonschema:"Optional repository owner"`
	Repo         string   `json:"repo,omitempty" jsonschema:"Optional repository name"`
	Kind         string   `json:"kind,omitempty" jsonschema:"Optional thread kind"`
	State        string   `json:"state,omitempty"`
	StateReason  string   `json:"state_reason,omitempty"`
	Merged       *bool    `json:"merged,omitempty"`
	Author       string   `json:"author,omitempty"`
	Association  string   `json:"author_association,omitempty"`
	Assignee     string   `json:"assignee,omitempty"`
	Labels       []string `json:"labels,omitempty"`
	UpdatedAfter string   `json:"updated_after,omitempty"`
	Limit        int      `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
	Cursor       string   `json:"cursor,omitempty" jsonschema:"Opaque cursor returned by the previous page"`
}

SearchInput describes an offline thread search page.

type SearchOutput 

type SearchOutput struct {
	Query      string         `json:"query"`
	Matches    []ThreadOutput `json:"matches"`
	Total      int            `json:"total"`
	NextCursor string         `json:"next_cursor,omitempty"`
}

SearchOutput contains one page of offline thread matches.

type SearchRepositoriesInput 

type SearchRepositoriesInput struct {
	Query  string `json:"query,omitempty" jsonschema:"Full-text query over repository owner, name, and description"`
	Owner  string `json:"owner,omitempty" jsonschema:"Optional repository owner"`
	Repo   string `json:"repo,omitempty" jsonschema:"Optional repository name"`
	Limit  int    `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
	Cursor string `json:"cursor,omitempty" jsonschema:"Opaque cursor returned by the previous page"`
}

SearchRepositoriesInput describes an offline repository search page.

type SearchRepositoriesOutput 

type SearchRepositoriesOutput struct {
	Query      string             `json:"query"`
	Total      int                `json:"total"`
	Matches    []RepositoryOutput `json:"matches"`
	NextCursor string             `json:"next_cursor,omitempty"`
}

SearchRepositoriesOutput contains one page of repository matches.

type SearchThreadsInput 

type SearchThreadsInput struct {
	Query        string   `json:"query" jsonschema:"Full-text query over thread titles and bodies"`
	Owner        string   `json:"owner,omitempty" jsonschema:"Optional repository owner"`
	Repo         string   `json:"repo,omitempty" jsonschema:"Optional repository name"`
	Kind         string   `json:"kind,omitempty" jsonschema:"Optional thread kind: issue or pull_request"`
	State        string   `json:"state,omitempty" jsonschema:"Optional open or closed state"`
	StateReason  string   `json:"state_reason,omitempty" jsonschema:"Optional GitHub completed or not_planned state reason"`
	Merged       *bool    `json:"merged,omitempty" jsonschema:"Optional pull request merged state"`
	Author       string   `json:"author,omitempty" jsonschema:"Optional author login"`
	Association  string   `json:"author_association,omitempty" jsonschema:"Optional GitHub author association"`
	Assignee     string   `json:"assignee,omitempty" jsonschema:"Optional assignee login"`
	Labels       []string `json:"labels,omitempty" jsonschema:"Labels that must all be present"`
	UpdatedAfter string   `json:"updated_after,omitempty" jsonschema:"Optional RFC 3339 lower bound"`
	Limit        int      `json:"limit,omitempty" jsonschema:"Maximum results from 1 to 100"`
	Cursor       string   `json:"cursor,omitempty" jsonschema:"Opaque cursor returned by the previous page"`
}

SearchThreadsInput describes an offline issue and pull-request search page.

type SearchWarning added in v0.7.0 

type SearchWarning struct {
	Code       string `json:"code"`
	Message    string `json:"message"`
	Suggestion string `json:"suggestion,omitempty"`
}

SearchWarning explains a request-specific limitation and how to improve it.

type Server 

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

Server owns the MCP protocol adapter around a local Reader.

func New 

func New(reader Reader, version string) *Server

New constructs an MCP server over reader and registers all supported tools and resources. A blank version is reported as "dev".

func (*Server) MCP 

func (s *Server) MCP() *mcp.Server

MCP returns the underlying SDK server for embedding in another transport.

func (*Server) ServeStdio 

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

ServeStdio serves MCP messages over standard input and output until the context is cancelled or the transport stops.

type SourceRef 

type SourceRef struct {
	Source     string `json:"source" jsonschema:"Source identifier"`
	URL        string `json:"url,omitempty" jsonschema:"Source URL"`
	CommitSHA  string `json:"commit_sha,omitempty" jsonschema:"Source commit SHA"`
	ObservedAt string `json:"observed_at,omitempty" jsonschema:"Observation timestamp"`
	AsOf       string `json:"as_of,omitempty" jsonschema:"As-of timestamp"`
}

SourceRef records provenance for an MCP result or workflow artifact.

type StartInvestigationInput 

type StartInvestigationInput struct {
	Owner     string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo      string `json:"repo" jsonschema:"GitHub repository name"`
	CommitSHA string `json:"commit_sha,omitempty" jsonschema:"Optional commit SHA"`
	Lens      string `json:"lens,omitempty" jsonschema:"Optional lens name"`
}

StartInvestigationInput creates a local investigation for a repository revision.

type SuggestedAction added in v0.7.0 

type SuggestedAction struct {
	Tool      string         `json:"tool"`
	Reason    string         `json:"reason"`
	Arguments map[string]any `json:"arguments,omitempty"`
}

SuggestedAction describes a non-mandatory follow-up with reusable arguments.

type SyncAuthoredPullRequestsInput added in v0.5.0 

type SyncAuthoredPullRequestsInput struct {
	State        string `json:"state,omitempty" jsonschema:"open, closed, or all"`
	UpdatedAfter string `json:"updated_after,omitempty" jsonschema:"Optional RFC 3339 lower bound"`
	Limit        int    `json:"limit,omitempty" jsonschema:"Maximum authored pull requests from 1 to 500"`
}

SyncAuthoredPullRequestsInput bounds authored pull-request discovery and refresh.

type SyncPullRequestStatusInput added in v0.5.0 

type SyncPullRequestStatusInput struct {
	PullRequests []ThreadRef `json:"pull_requests" jsonschema:"One to 50 exact pull requests"`
	MaxPages     int         `json:"max_pages,omitempty" jsonschema:"Maximum review pages from 1 to 20"`
}

SyncPullRequestStatusInput selects pull requests and bounds review hydration.

type SyncRepositoryMetadataInput added in v0.5.0 

type SyncRepositoryMetadataInput struct {
	Repositories []RepositoryRef `json:"repositories" jsonschema:"One to 100 explicit repositories"`
}

SyncRepositoryMetadataInput selects repositories for asynchronous metadata refresh.

type SyncThreadsInput added in v0.5.0 

type SyncThreadsInput struct {
	Selection          string          `json:"selection" jsonschema:"repositories or threads"`
	Repositories       []RepositoryRef `json:"repositories,omitempty" jsonschema:"One to 50 repositories in repository mode"`
	Threads            []ThreadRef     `json:"threads,omitempty" jsonschema:"One to 100 exact threads in thread mode"`
	Kind               string          `json:"kind,omitempty" jsonschema:"issue, pull_request, or both in repository mode"`
	State              string          `json:"state,omitempty" jsonschema:"open, closed, or all in repository mode"`
	UpdatedAfter       string          `json:"updated_after,omitempty" jsonschema:"Optional RFC 3339 lower bound in repository mode"`
	LimitPerRepository int             `json:"limit_per_repository,omitempty" jsonschema:"Maximum headers per repository from 1 to 1000"`
}

SyncThreadsInput selects either bounded repository-wide header discovery or exact thread refresh. It never requests child comments, reviews, or code.

type ThreadByNumberInput 

type ThreadByNumberInput struct {
	Owner  string `json:"owner"`
	Repo   string `json:"repo"`
	Number int    `json:"number"`
}

ThreadByNumberInput identifies a stored issue or pull request by number.

type ThreadInput 

type ThreadInput struct {
	Owner  string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo   string `json:"repo" jsonschema:"GitHub repository name"`
	Kind   string `json:"kind" jsonschema:"Thread kind: issue or pull_request"`
	Number int    `json:"number" jsonschema:"GitHub issue or pull request number"`
}

ThreadInput identifies an issue or pull request for an MCP operation.

type ThreadOutput 

type ThreadOutput struct {
	Owner             string   `json:"owner"`
	Repo              string   `json:"repo"`
	Kind              string   `json:"kind"`
	Number            int      `json:"number"`
	State             string   `json:"state"`
	StateReason       string   `json:"state_reason,omitempty"`
	Title             string   `json:"title"`
	Body              string   `json:"body,omitempty"`
	Author            string   `json:"author,omitempty"`
	AuthorAssociation string   `json:"author_association,omitempty"`
	Labels            []string `json:"labels,omitempty"`
	Assignees         []string `json:"assignees,omitempty"`
	Draft             bool     `json:"draft,omitempty"`
	ClosedAt          string   `json:"closed_at,omitempty"`
	MergedAt          string   `json:"merged_at,omitempty"`
	Merged            bool     `json:"merged,omitempty"`
	UpdatedAt         string   `json:"updated_at,omitempty"`
}

ThreadOutput is the stable MCP representation of an issue or pull request.

type ThreadRef added in v0.5.0 

type ThreadRef struct {
	Owner  string `json:"owner" jsonschema:"GitHub repository owner"`
	Repo   string `json:"repo" jsonschema:"GitHub repository name"`
	Kind   string `json:"kind,omitempty" jsonschema:"Optional thread kind: issue or pull_request"`
	Number int    `json:"number" jsonschema:"Positive issue or pull request number"`
}

ThreadRef identifies an exact issue or pull request. Kind may be omitted only for tools that intentionally resolve a number without a preselected kind.

type ToolError added in v0.7.0 

type ToolError struct {
	Code             string            `json:"code"`
	Message          string            `json:"message"`
	Field            string            `json:"field,omitempty"`
	Retryable        bool              `json:"retryable"`
	Example          map[string]any    `json:"example,omitempty"`
	SuggestedActions []SuggestedAction `json:"suggested_actions,omitempty"`
}

ToolError is the stable, actionable shape used for agent-correctable errors. Error keeps the code, field, and example visible when an MCP client only transports the error message rather than structured error data.

func (*ToolError) Error added in v0.7.0 

func (e *ToolError) Error() string

type TypedRepositoryOutput added in v0.5.0 

type TypedRepositoryOutput struct {
	Ref           string                   `json:"ref"`
	Owner         string                   `json:"owner"`
	Repo          string                   `json:"repo"`
	Metadata      RepositoryMetadataOutput `json:"metadata"`
	Description   *string                  `json:"description"`
	DefaultBranch *string                  `json:"default_branch"`
	Language      *string                  `json:"language"`
	License       *string                  `json:"license"`
	Topics        []string                 `json:"topics,omitempty"`
	Stars         *int                     `json:"stars"`
	Watchers      *int                     `json:"watchers"`
	Forks         *int                     `json:"forks"`
	OpenIssues    *int                     `json:"open_issues"`
	Archived      *bool                    `json:"archived"`
	Fork          *bool                    `json:"fork"`
}

TypedRepositoryOutput contains repository facts with explicit metadata coverage.

type ValidationOutput 

type ValidationOutput struct {
	ID              string   `json:"id"`
	InvestigationID string   `json:"investigation_id"`
	Kind            string   `json:"kind"`
	Command         []string `json:"command"`
	WorkingDir      string   `json:"working_dir"`
	BaseWorkingDir  string   `json:"base_working_dir,omitempty"`
	CandidateDir    string   `json:"candidate_dir,omitempty"`
	Env             []string `json:"environment_allowlist,omitempty"`
	Timeout         string   `json:"timeout,omitempty"`
	MaxOutputBytes  int64    `json:"max_output_bytes,omitempty"`
	CreatedAt       string   `json:"created_at"`
}

ValidationOutput is the stable MCP representation of a validation definition.

type WorkflowPromptRef 

type WorkflowPromptRef struct {
	Name        string            `json:"name"`
	Description string            `json:"description"`
	Arguments   map[string]string `json:"arguments,omitempty"`
}

WorkflowPromptRef describes an MCP prompt useful for a workflow.

type WorkflowResourceRef 

type WorkflowResourceRef struct {
	URI         string `json:"uri"`
	Description string `json:"description"`
	Capability  string `json:"capability"`
}

WorkflowResourceRef describes a local MCP resource used by a workflow.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.