mcp

package
v0.13.0 Latest Latest
Warning

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

 Go to latest Published: Jul 25, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package mcp exposes ketch's search, code, docs, scrape, and crawl capabilities as Model Context Protocol (MCP) tools. Each tool adapter calls the same underlying packages (search, code, docs, scrape, crawl) the Cobra commands in cmd/ call, through the same config-driven constructors (search.NewFromConfig etc.), and resolves backends from the same *config.Config an agent's human counterpart configures via `ketch config set`.

The go-sdk dispatches tool calls concurrently, so everything with process lifetime (the headless-browser scraper, the bbolt page cache, the compiled URL rewriter) is constructed once in NewServer, shared by all calls, and released in Close — never per call.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type CodeInput 

type CodeInput struct {
	Query   string `json:"query" jsonschema:"the code search query"`
	Backend string `json:"backend,omitempty" jsonschema:"code search backend: grepapp, sourcegraph, or github (default: the configured backend)"`
	Lang    string `json:"lang,omitempty" jsonschema:"language filter appended to the query"`
	Limit   int    `json:"limit,omitempty" jsonschema:"max number of results (default: the configured limit)"`
	Regexp  bool   `json:"regexp,omitempty" jsonschema:"interpret query as a regular expression (grepapp, sourcegraph only)"`
}

CodeInput is the input schema for the "code" tool.

type CodeOutput 

type CodeOutput struct {
	Results []code.Result `json:"results"`
}

CodeOutput is the output schema for the "code" tool. Results carries the same result objects as the CLI's `ketch code --json` (which emits them as a bare array; MCP structured content needs the object wrapper).

type CrawlError 

type CrawlError struct {
	URL   string `json:"url"`
	Error string `json:"error"`
}

CrawlError is a per-URL crawl failure. The crawl keeps going; these are reported alongside the pages that did succeed.

type CrawlInput 

type CrawlInput struct {
	URL      string   `json:"url" jsonschema:"seed URL to crawl (BFS, same host only)"`
	Depth    int      `json:"depth,omitempty" jsonschema:"max BFS depth (default 3)"`
	Sitemap  bool     `json:"sitemap,omitempty" jsonschema:"treat the seed URL as a sitemap"`
	MaxPages int      `json:"max_pages,omitempty" jsonschema:"stop after this many pages (default 30, capped at 100)"`
	Allow    []string `json:"allow,omitempty" jsonschema:"path substring filters; a URL must contain at least one to be crawled"`
	Deny     []string `json:"deny,omitempty" jsonschema:"regex patterns; matching URLs are skipped"`
	MaxChars int      `json:"max_chars,omitempty" jsonschema:"truncate each page's markdown to N characters (0 = disabled)"`
	NoCache  bool     `json:"no_cache,omitempty" jsonschema:"bypass the page cache"`
}

CrawlInput is the input schema for the "crawl" tool.

type CrawlOutput 

type CrawlOutput struct {
	Pages   []CrawlPage  `json:"pages"`
	Errors  []CrawlError `json:"errors,omitempty"`
	Stopped string       `json:"stopped,omitempty"`
}

CrawlOutput is the output schema for the "crawl" tool. Stopped is set when the crawl was cut short by the server-side page budget ("max_pages") or wall-clock timeout ("timeout"); the collected pages are still returned.

type CrawlPage 

type CrawlPage struct {
	URL      string `json:"url"`
	Title    string `json:"title"`
	Markdown string `json:"markdown"`
}

CrawlPage is one crawled page in the "crawl" tool output.

type DocsInput 

type DocsInput struct {
	Query   string `json:"query" jsonschema:"the docs search query, or a library name when resolve is true"`
	Backend string `` /* 126-byte string literal not displayed */
	Library string `` /* 143-byte string literal not displayed */
	Tokens  int    `json:"tokens,omitempty" jsonschema:"Context7 token budget when library is set (default 4000)"`
	Limit   int    `json:"limit,omitempty" jsonschema:"max number of results (default: the configured limit)"`
	Resolve bool   `json:"resolve,omitempty" jsonschema:"resolve a library name to Context7 library IDs instead of searching docs"`
}

DocsInput is the input schema for the "docs" tool.

type DocsOutput 

type DocsOutput struct {
	Results []docs.Result       `json:"results,omitempty"`
	Matches []docs.LibraryMatch `json:"matches,omitempty"`
}

DocsOutput is the output schema for the "docs" tool. Results is populated for a normal or library-scoped search; Matches is populated when Resolve is set. Exactly one of the two is non-empty for a given call. The result objects match the CLI's `ketch docs --json` (which emits a bare array; MCP structured content needs the object wrapper).

type ScrapeInput 

type ScrapeInput struct {
	URL          string   `json:"url,omitempty" jsonschema:"the URL to scrape (exactly one of url or urls)"`
	URLs         []string `` /* 136-byte string literal not displayed */
	Selector     string   `json:"selector,omitempty" jsonschema:"CSS selector to extract specific elements, skips readability (incompatible with raw)"`
	Trim         bool     `json:"trim,omitempty" jsonschema:"strip markdown formatting, keep content text only (incompatible with raw)"`
	MaxChars     int      `json:"max_chars,omitempty" jsonschema:"truncate markdown (or raw HTML) output to N characters per page (0 = disabled)"`
	NoCache      bool     `json:"no_cache,omitempty" jsonschema:"bypass the page cache"`
	Raw          bool     `json:"raw,omitempty" jsonschema:"return raw HTML in raw_html instead of extracted markdown"`
	ForceBrowser bool     `` /* 159-byte string literal not displayed */
	NoLLMSTxt    bool     `json:"no_llms_txt,omitempty" jsonschema:"disable automatic /llms.txt detection for bare domain URLs"`
	Concurrency  int      `json:"concurrency,omitempty" jsonschema:"max concurrent fetches for multi-URL scrapes (default 5, capped at 16)"`
}

ScrapeInput is the input schema for the "scrape" tool. Exactly one of url or urls must be provided. The options mirror the per-invocation flags of `ketch scrape`; the CLI's file/stdin input modes don't apply here.

type ScrapeOutput 

type ScrapeOutput struct {
	Results []ScrapeResult `json:"results"`
}

ScrapeOutput is the output schema for the "scrape" tool: one entry per requested URL, in input order.

type ScrapeResult 

type ScrapeResult struct {
	scrape.Page
	Source  string `json:"source,omitempty" jsonschema:"fetch path that produced the page (http, http_shell, browser); raw mode only"`
	RawHTML string `json:"raw_html,omitempty" jsonschema:"raw page HTML; set when raw is true"`
	Error   string `json:"error,omitempty" jsonschema:"per-URL failure (batch scrapes only); other fields are empty when set"`
}

ScrapeResult is one scraped page. It embeds scrape.Page — the same object `ketch scrape --json` emits — plus the raw-mode fields (source, raw_html) and a per-URL error slot used by batch scrapes.

type SearchInput 

type SearchInput struct {
	Query      string   `json:"query" jsonschema:"the search query"`
	Backend    string   `` /* 136-byte string literal not displayed */
	Multi      []string `` /* 287-byte string literal not displayed */
	Random     []string `` /* 206-byte string literal not displayed */
	Limit      int      `json:"limit,omitempty" jsonschema:"max number of results (default: the configured limit)"`
	SearxngURL string   `json:"searxng_url,omitempty" jsonschema:"override the configured SearXNG instance URL (searxng backend only)"`
	Scrape     bool     `json:"scrape,omitempty" jsonschema:"also fetch each result URL and fill its content field with extracted markdown"`
	Trim       bool     `json:"trim,omitempty" jsonschema:"strip markdown formatting from scraped content, keep text only (with scrape)"`
	MaxChars   int      `json:"max_chars,omitempty" jsonschema:"truncate each result's scraped content to N characters (with scrape; 0 = disabled)"`
}

SearchInput is the input schema for the "search" tool. It mirrors the per-invocation flags of `ketch search`; config-level settings (API keys, default backend/limit) stay operator-configured.

type SearchOutput 

type SearchOutput struct {
	Results []search.Result   `json:"results"`
	Backend string            `json:"backend,omitempty"`
	Errors  map[string]string `json:"errors,omitempty"`
}

SearchOutput is the output schema for the "search" tool. Results carries the same result objects as the CLI's `ketch search --json` (which emits them as a bare array; MCP structured content needs the object wrapper). Backend names the selected provider under random search. Errors maps a backend name to its failure message under multi or random search, so callers can see which providers were dropped or tried before the winner.

type Server 

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

Server bundles the SDK server with the shared, server-lifetime resources the tool handlers use. Construct with NewServer, run with Run, and always Close when done (it shuts down the headless browser and releases the cache file lock).

func NewServer 

func NewServer(cfg *config.Config, version string) (*Server, error)

NewServer builds an MCP server named "ketch" exposing the search, code, docs, scrape, and crawl tools, backed by cfg for backend selection and API keys. Background crawls, cache admin, and config stay CLI-only.

The returned error is a precondition failure (invalid url_rewrites config). A nil cache (e.g. another long-lived process holds the bbolt lock) is not an error: the server runs with caching disabled, exactly like the CLI.

func (*Server) Close 

func (s *Server) Close()

Close releases the server-lifetime resources: kills the headless browser (if one was launched) and closes the page cache. Safe to call once Run has returned; both underlying Closes are nil-safe.

func (*Server) Run 

func (s *Server) Run(ctx context.Context, t mcpsdk.Transport) error

Run runs the server over the given transport until the client disconnects or ctx is cancelled. Call Close afterwards to release shared resources.

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.