python-sdk Completions 完整指南：为 Prompt 参数与资源模板实现智能补全

人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载本指南基于官方 Python SDK 的 Completions 文档完整讲解如何在 MCP 服务器上通过mcp.completion()注册补全处理器为prompt 参数与资源模板参数提供输入时的自动建议。读完你将掌握补全处理器的三参数签名、Completion/None返回值语义、依赖参数context_arguments的级联补全写法以及「处理器即能力声明」的底层机制。什么内容值得补全Something worth completing当客户端在服务器之上构建 UI、用户在输入框中打字时它需要为参数值提供自动补全语言名称、仓库名、文件路径……completions正是服务器向 UI 提供这些建议的机制。需要明确边界completions 只适用于两样东西——某个prompt的参数以及某个**资源模板resource template**的参数。除此之外别无他用。因此先从同时包含这两类入口的服务器开始。以下示例注册了一个带language、code参数的review_codeprompt以及一个带owner、repo参数的github://repos/{owner}/{repo}资源模板源码见 docs_src/completions/tutorial001.pyfrom mcp.server import MCPServer mcp MCPServer(GitHub Explorer) mcp.resource(github://repos/{owner}/{repo}) def github_repo(owner: str, repo: str) - str: A GitHub repository. return fRepository: {owner}/{repo} mcp.prompt() def review_code(language: str, code: str) - str: Review a snippet of code. return fReview this {language} code:\n{code}这个阶段还没有任何补全逻辑但两个需要补全的痛点已经清晰review_code接收language——用户不应靠猜来得知你接受哪些拼写是python还是Pythongithub_repo接收owner和repo——两个自由文本输入框会组成一个体验很差的表单。补全处理器The completion handler为服务器添加一个用mcp.completion()装饰的函数即可完整代码见 docs_src/completions/tutorial002.pyfrom mcp.server import MCPServer from mcp.types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference mcp MCPServer(GitHub Explorer) LANGUAGES [go, javascript, python, rust, typescript] mcp.resource(github://repos/{owner}/{repo}) def github_repo(owner: str, repo: str) - str: A GitHub repository. return fRepository: {owner}/{repo} mcp.prompt() def review_code(language: str, code: str) - str: Review a snippet of code. return fReview this {language} code:\n{code} mcp.completion() async def handle_completion( ref: PromptReference | ResourceTemplateReference, argument: CompletionArgument, context: CompletionContext | None, ) - Completion | None: if isinstance(ref, PromptReference) and argument.name language: return Completion(values[lang for lang in LANGUAGES if lang.startswith(argument.value)]) return None处理器要点每台服务器只有一个处理器。所有补全请求都会汇聚到这里你需要根据“正在补全什么”自行分支。必须是async defSDK 会对它做 await。从源码看装饰器在 src/mcp/server/mcpserver/server.py 中把用户函数包进了一个异步 handler并注册到低层服务器的completion/complete请求处理器上。三个入参ref指明是哪个prompt 或资源模板类型为PromptReference或ResourceTemplateReference。用isinstance来区分两者。argumentargument.name是正在被补全的参数名argument.value是用户到目前为止输入的内容即前缀。context已经解析出的参数值暂可忽略下一节会用到。返回值返回Completion(values[...])当无可建议时返回None。前缀过滤由你负责argument.value是用户输入的前缀SDK 不会替你过滤你放进values的内容就是 UI 展示的内容startswith过滤必须由你自己写。这正是示例中lang.startswith(argument.value)这一行的由来——这也是代码中唯一的“智能”所在。动手试一下Try it使用 Testing 文档中介绍的内存版Client来驱动它。调用client.complete()传入refPromptReference(namereview_code)和argument{name: language, value: py}result.completion.values # [python]ref与处理器收到的引用是同一类型。argument是一个恰好包含name和value两个键的普通 dict。传入空的value会得到完整列表——lang.startswith()对每种语言都为真result.completion.values # [go, javascript, python, rust, typescript]询问code一个处理器不认识的参数时处理器返回NoneSDK 会把它转换成空列表result.completion.values # []None的含义是*“没有建议”*永远不会是错误。UI 收到空列表后会退化为普通的文本输入框表单依然可用。从客户端侧看client.complete()的方法签名定义在 src/mcp/client/client.py它委托给 src/mcp/client/session.py 中的会话层argumentdict 被展开为CompletionArgument(**argument)最终封装成CompleteRequest发送出去——这正是处理器侧收到的三个参数对应的协议形态。一项你从未声明过的能力A capability you never declared注册处理器本身就是能力的声明。接上客户端看一眼client.server_capabilities.completions # CompletionsCapability()你并没有在任何地方列出completions但 SDK 看到你注册了处理器就自动替你声明了该能力。所有可选能力都是如此处理器即声明。三个基础原语——如tools、resources、prompts——不属于可选能力MCPServer无论有没有处理器都会声明它们。这一自动声明在源码中同样有迹可循低层服务器在 src/mcp/server/lowlevel/server.py 构建CompletionsCapability()并纳入服务器能力列表。验证反例回到第一个server.py没有处理器的那个照常发起请求调用会以 JSON-RPC 错误失败Method not found此时client.server_capabilities.completions是None。这正是能力capability存在的意义行为良好的客户端会先检查能力再发请求永远不会把请求发给一个无法应答的服务器。依赖参数Dependent argumentsgithub://repos/{owner}/{repo}有两个参数而repo的可用取值依赖于用户先前选择的owner。这就要用到context了它携带用户已经解析的参数值。完整代码见 docs_src/completions/tutorial003.pyfrom mcp.server import MCPServer from mcp.types import Completion, CompletionArgument, CompletionContext, PromptReference, ResourceTemplateReference mcp MCPServer(GitHub Explorer) LANGUAGES [go, javascript, python, rust, typescript] REPOS_BY_OWNER { modelcontextprotocol: [python-sdk, typescript-sdk, inspector], pydantic: [pydantic, pydantic-ai, logfire], } mcp.resource(github://repos/{owner}/{repo}) def github_repo(owner: str, repo: str) - str: A GitHub repository. return fRepository: {owner}/{repo} mcp.prompt() def review_code(language: str, code: str) - str: Review a snippet of code. return fReview this {language} code:\n{code} mcp.completion() async def handle_completion( ref: PromptReference | ResourceTemplateReference, argument: CompletionArgument, context: CompletionContext | None, ) - Completion | None: if isinstance(ref, PromptReference) and argument.name language: return Completion(values[lang for lang in LANGUAGES if lang.startswith(argument.value)]) if isinstance(ref, ResourceTemplateReference) and argument.name repo: if context is None or context.arguments is None: return None repos REPOS_BY_OWNER.get(context.arguments.get(owner, ), []) return Completion(values[repo for repo in repos if repo.startswith(argument.value)]) return None要点拆解新增的分支针对模板的repo参数触发context.arguments是dict[str, str] | None保存着迄今已选定的值这里是owner还没有owner时没有任何合理的建议可给所以处理器返回None。客户端通过context_arguments发送这些已解析的值。这一次ref是ResourceTemplateReference(urigithub://repos/{owner}/{repo})——注意资源模板的引用由完整 URI 构成。以空value请求repo并传入context_arguments{owner: modelcontextprotocol}result.completion.values # [python-sdk, typescript-sdk, inspector]去掉context_arguments同样的调用返回[]——在知道 owner 是谁之前处理器无从得知该提供哪些仓库。大量结果的表达Completion还接受total和has_more两个参数。当values只是更长列表中的一个切片时设置它们UI 就能显示*“还有 200 个”*之类的提示。大多数处理器永远用不到这两个参数但接口上它们是开放的如 src/mcp/server/mcpserver/server.py 所示None被转换为Completion(values[], totalNone, has_moreNone)。完整代码速查三个递进版本均可直接运行查看阶段源码位置要点基础版docs_src/completions/tutorial001.py仅注册 prompt 与资源模板无补全逻辑单参数补全docs_src/completions/tutorial002.py单一mcp.completion()处理器 startswith前缀过滤依赖参数补全docs_src/completions/tutorial003.py通过context.arguments实现owner → repo级联补全仓库中对应的测试位于 tests/docs_src/test_completions.py可结合测试用例验证各阶段的预期行为前缀过滤、空值返回完整列表、未知参数返回空列表、依赖参数等场景。总结RecapCompletions 是为prompt 参数和资源模板参数提供建议仅此而已。mcp.completion()注册唯一的处理器签名为async def (ref, argument, context) - Completion | None。用isinstance(ref, ...)和argument.name进行分支argument.value的前缀过滤由你自己实现。None会变成空列表永远不会是错误。context.arguments保存已解析的参数值客户端以context_arguments提供。注册处理器的瞬间completions能力即被自动声明没有处理器时请求会返回Method not found。补全建议在用户仍处于填写prompt 或模板阶段时发挥作用若需要在一次工具调用的中途向用户提问应使用 Elicitationelicitation机制工具除文本外还能返回的一切内容参见 Imagens, áudio e ícones。赞分享人工智能MCP 服务MCP Clients【免费下载链接】python-sdkThe official Python SDK for Model Context Protocol servers and clients项目地址https://gitcode.com/gh_mirrors/pythonsd/python-sdk点击查看免费下载相关推荐MCP Python SDK 服务端 Completions 完整指南为 Prompt 参数与资源模板实现自动补全MCP Python SDK 服务端 Completions 完整指南为 Prompt 参数与资源模板实现自动补全 导读 当客户端在你的 MCP 服务之上构建人工智能MCP 服务MCP ClientsMCP Python SDK 自动补全Completions实战为提示词参数与资源模板参数实现智能建议MCP Python SDK 自动补全Completions实战为提示词参数与资源模板参数实现智能建议 自动补全Completions是 MCP 协议人工智能MCP 服务MCP Clientspython-sdk 服务器端自动补全Completions完整实战指南从 Prompt 参数到资源模板依赖补全python sdk 服务器端自动补全Completions完整实战指南从 Prompt 参数到资源模板依赖补全 本指南围绕官方 Python SDKp人工智能MCP 服务MCP Clients上一篇Oracle Docker 镜像中 Instant Client 的深度解析与应用指南下一篇ContextGem实战案例构建企业级合同分析系统的完整流程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考