doc

package
v0.1.5 Latest Latest
Warning

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

Go to latest
Published: Nov 14, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package doc loads a tree of markdown and serves it over MCP: everything outside the prompts subtree as a resource, the prompts subtree as prompts. Both are markdown with YAML frontmatter, read from one fs.FS at startup — an embed.FS in production, an os.DirFS in a dev run so that editing a file needs no rebuild, an fstest.MapFS in a test.

md/targets/grafana.md     → resource <scheme>targets/grafana.md
md/prompts/investigate.md → prompt  "investigate"

The library speaks the protocol types directly: *Library is what mcpkit.NewResourcesService and mcpkit.NewPromptsService take, with no adapter in between and no second vocabulary for the same thing.

Index

Constants

View Source
const (
	MimeMarkdown = "text/markdown"
	MimeYAML     = "application/yaml"
	MimeTOML     = "application/toml"
)

MIME types the standard library does not know.

View Source
const DefaultDescMaxLen = 240

DefaultDescMaxLen caps, in bytes, a description derived from the body of a file. Bytes and not characters because what this cap protects is the size of resources/list, which every client pays for on connect.

View Source
const DefaultPromptsDir = "prompts"

DefaultPromptsDir is the subtree that holds prompts when Options names none.

Variables

This section is empty.

Functions

This section is empty.

Types

type Library

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

Library is an in-memory index of everything loaded from one fs.FS.

func Load

func Load(fsys fs.FS, root string, opts Options) (*Library, error)

Load walks fsys from root and indexes every regular file: markdown under the prompts subtree as a prompt, everything else as a resource.

A nil fsys produces an empty library rather than an error — a dev run with no documents still has to boot.

func (*Library) Entry added in v0.1.3

func (l *Library) Entry(uri string) (mcp.ResourceEntry, bool)

Entry returns the catalogue entry of a resource by URI, accepting the canonical URI or the bare path.

It is the half of Read that costs nothing. The name, title, description, MIME type and size were indexed at startup, and a caller that only wants to say what a document is — a help tool naming what it can read, a tool quoting the description of the page it is about to point at — has no reason to open the file to find out, nor to keep a second map of the same thing beside this one.

func (*Library) NormalizeURI

func (l *Library) NormalizeURI(uri string) string

NormalizeURI expands a bare path to the canonical URI and leaves an already-canonical URI untouched.

It is not cosmetic: these URIs arrive typed by the model out of instruction text, and the scheme goes missing regularly.

func (*Library) Prompt

func (l *Library) Prompt(name string) (mcp.PromptEntry, error)

Prompt returns one prompt's declaration by name.

func (*Library) Prompts

func (l *Library) Prompts() []mcp.PromptEntry

Prompts returns every loaded prompt, sorted by name. The slice is shared — do not mutate it.

func (*Library) Read

func (l *Library) Read(uri string) ([]byte, string, error)

Read returns the bytes and MIME type of a resource by URI, accepting the canonical URI or the bare path.

func (*Library) Render

func (l *Library) Render(name string, args map[string]string) (description, text string, err error)

Render fills the placeholders of a prompt and returns its description and the finished text. An unknown argument renders as an empty string; a missing required one is an error.

func (*Library) Resources

func (l *Library) Resources() []mcp.ResourceEntry

Resources returns every loaded resource in walk order. The slice is shared — do not mutate it.

type Options

type Options struct {
	// URIScheme prefixes every resource URI, e.g. "docs://" or "srv://catalog/".
	// Required: a library with no scheme cannot name its resources.
	URIScheme string
	// PromptsDir is the one subtree that holds prompts. Empty means
	// DefaultPromptsDir.
	PromptsDir string
	// DescMaxLen caps, in bytes, a description derived from the body; 0 means
	// DefaultDescMaxLen.
	DescMaxLen int
}

Options configures Load.

Jump to

Keyboard shortcuts

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