mcp

package
v1.0.0-rc.39 Latest Latest
Warning

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

Go to latest
Published: Oct 24, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package mcp 是 pt-tools 的 MCP(Model Context Protocol)服务(路线图 M14):工具定义、权限检查与写操作的审计。

工具本身不碰数据库与下载器:经 Backend 在进程内调用 App API v1(web 实现),所以返回的字段、脱敏与 App API 完全一样。 传输在别处接:主端口的 streamable HTTP(/mcp,web 包)与 stdio 桥(pt-tools mcp,cmd 包)。

权限分两层:HTTP 层只放行有 mcp:read 或 mcp:write 的 API 令牌;工具分派时只读工具要 mcp:read,写工具要 mcp:write, 写工具还要 confirm=true。写工具的每次调用(包括被拒的)记操作审计,通道是 mcp,命令是工具名。

Index

Constants

View Source
const (
	SkillConfig = "pt-tools-config"
	SkillFollow = "pt-tools-follow"
	SkillTool   = "get_skill"
)

SkillConfig 是配置技能的名字,SkillFollow 是追剧技能的名字;SkillTool 是取技能的工具。

View Source
const ChannelType = "mcp"

ChannelType 是 MCP 写工具在操作审计里的通道。

View Source
const KindAssistant = "assistant"

KindAssistant 是内置 AI 助手(internal/assistant):它在进程内连一个 MCP 服务调工具,审计记在这个通道下。

Variables

View Source
var ConfigTools = []string{"get_config", "change_config"}

ConfigTools 是要 app:config 的工具:内置 AI 助手在入口没有配置权限时不把它们交给模型。

View Source
var ToolNames = []string{
	"list_tasks", "list_downloader_torrents", "get_downloader_stats", "search_torrents",
	"pause_torrent", "resume_torrent", "delete_torrent", "push_torrent",
	"get_site_userinfo", "check_updates",
	"explore_media", "list_subscriptions", "add_subscription",
	"get_subscription", "set_subscription_status", "search_subscription", "delete_subscription",
	"update_subscription", "list_subscription_runs", "set_episode_skip", "unlock_episode",
	"get_episode_rules", "save_episode_rule", "delete_episode_rule", "preview_schedule",
	"reorganize_subscription_torrent", "rescrape_subscription_torrent",
	"recognize_media", "list_media_libraries", "list_media_history", "preview_media_organize", "organize_media",
	"retry_media_organize", "rescrape_media", "get_config", "change_config", "get_skill",
}

ToolNames 是全部工具的名字(文档与测试用)。

Functions

func NewServer

func NewServer(d Deps) *sdk.Server

NewServer 建 MCP 服务,注册全部工具。

func TokenInfo

func TokenInfo(c Caller, expires time.Time) *auth.TokenInfo

TokenInfo 把令牌换成 go-sdk 的 TokenInfo(HTTP 层校验令牌以后放进请求,工具从 req.Extra.TokenInfo 取回来)。 expires 为零表示不过期。

Types

type Auditor

type Auditor interface {
	Record(ctx context.Context, e app.AuditEntry) error
}

Auditor 记操作审计(app.AuditService 实现了它)。

type Backend

type Backend interface {
	Call(ctx context.Context, c Caller, req Request) (Response, error)
}

Backend 在进程内调用 App API v1(web.Server 实现)。

type Caller

type Caller struct {
	TokenID uint
	Name    string
	Scopes  []string
	// Kind 为空是 /mcp 的 API 令牌;KindAssistant 是内置 AI 助手(Backend 据此选 App API 的主体种类)
	Kind string
	// Subject 是审计里的触发用户,例如 web:admin、chatops:3、device:2;为空时用令牌编号
	Subject string
}

Caller 是调用工具的一方:/mcp 上是 API 令牌;内置 AI 助手是会话的属主(Kind 为 KindAssistant,没有令牌编号)。

func CallerFromRequest

func CallerFromRequest(req *sdk.CallToolRequest) (Caller, bool)

CallerFromRequest 从工具请求里取调用的令牌(HTTP 层放进去的 TokenInfo);没有时 ok 为假。

func (Caller) Has

func (c Caller) Has(scope string) bool

Has 报告令牌有没有这个权限范围(精确匹配)。

type Change

type Change struct {
	Label  string `json:"label"`
	Before string `json:"before,omitempty"`
	After  string `json:"after,omitempty"`
	Secret bool   `json:"secret,omitempty"`
}

Change 是一项改动:改的是什么、改以前、改以后(新增的没有 Before,删掉的没有 After)。Secret 为真时是密钥,两边都不写原文。

type Deps

type Deps struct {
	Backend Backend
	Audit   Auditor
	// ResolveURL 把种子下载地址解析成已知站点与种子编号(push_torrent 的 torrent_url);不认识时 ok 为假
	ResolveURL func(rawURL string) (site, torrentID string, ok bool)
	// Version 是 pt-tools 的版本(initialize 时报给客户端)
	Version string
	// Caller 从工具请求里取令牌,默认 CallerFromRequest(测试里换掉;内置 AI 助手固定成这次运行的属主)
	Caller func(req *sdk.CallToolRequest) (Caller, bool)
	// Channel 是写工具在操作审计里的通道,为空时是 ChannelType(mcp)
	Channel string
}

Deps 是 MCP 服务的依赖。

type Preview

type Preview struct {
	Pending bool     `json:"pending"`
	Tool    string   `json:"tool"`
	Summary string   `json:"summary"`
	Changes []Change `json:"changes"`
	Impact  []string `json:"impact"`
	Note    string   `json:"note"`
}

Preview 是写工具的预览。Pending 总是真:这次没有执行。

type Request

type Request struct {
	Method string
	// Path 不带 /api/app/v1 前缀,可以带查询串
	Path string
	// Body 不为 nil 时按 JSON 编码
	Body any
	// Write 为真时按写接口调用(要 mcp:write)
	Write bool
	// Preview 为真时是写工具的预览读现状:令牌有 mcp:write 就能读(没有 mcp:read 也行)
	Preview bool
}

Request 是一次对 App API v1 的进程内调用。

type Response

type Response struct {
	Status int
	Body   []byte
	// Outcome 是写接口记下的业务结果(推送被拦下、批量动作全失败这类回 200 的失败),用审计的写法
	Outcome string
}

Response 是 App API 的回应。

Jump to

Keyboard shortcuts

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