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 ¶
const ( SkillConfig = "pt-tools-config" SkillFollow = "pt-tools-follow" SkillTool = "get_skill" )
SkillConfig 是配置技能的名字,SkillFollow 是追剧技能的名字;SkillTool 是取技能的工具。
const ChannelType = "mcp"
ChannelType 是 MCP 写工具在操作审计里的通道。
const KindAssistant = "assistant"
KindAssistant 是内置 AI 助手(internal/assistant):它在进程内连一个 MCP 服务调工具,审计记在这个通道下。
Variables ¶
var ConfigTools = []string{"get_config", "change_config"}
ConfigTools 是要 app:config 的工具:内置 AI 助手在入口没有配置权限时不把它们交给模型。
var ToolNames = []string{
"list_brush_tasks", "get_brush_task", "list_brush_runs", "change_brush_task",
"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 ¶
Types ¶
type Auditor ¶
type Auditor interface {
Record(ctx context.Context, e app.AuditEntry) error
}
Auditor 记操作审计(app.AuditService 实现了它)。
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 为假。
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 总是真:这次没有执行。