1. 为什么你的MCP服务器在Glama上得分低于70以及如何用一个下午修复它如果你正在为Claude构建MCP服务器并且已经把它提交到了awesome-mcp-servers这个主要的工具发现平台那你很可能已经注意到了那个小小的Glama评分徽章。它静静地躺在你的项目旁边显示着一个数字——通常是55到70之间。这个分数就像一个隐形的门槛分数高的项目更容易获得开发者的信任和采用而分数低的则可能被默默滑过。我见过太多优秀的工具实现因为文档描述的问题被这个评分系统严重低估了其实际价值。今天我们就来彻底拆解Glama的TDQS评分机制。这不是什么黑盒魔法而是一套非常具体、可操作的评估标准。更重要的是修复它并不需要你重写核心逻辑或进行大规模重构。正如标题所说你完全可以在一个下午的时间里通过调整工具的描述方式将分数从不及格拉升到优秀线以上。关键在于一次思维模式的转变从“为人类编写文档”转向“为LLM编写提示词”。让我们深入看看这到底是怎么回事。2. Glama TDQS评分机制深度解析Glama的评分系统全称为“工具描述质量评分”它并非评估你代码的运行效率或功能复杂性而是专门评估你的工具描述信息对于像Claude这样的大型语言模型来说是否清晰、完整、可操作。你可以把它想象成一位极其严格的产品经理专门审查你提交给AI的“产品说明书”。2.1 评分组件与权重分配整个评分体系由四个核心组件构成每个都有明确的权重组件权重核心检查点描述完整性25%是否清晰说明了工具的输入、输出和核心使用场景参数清晰度25%每个参数的名称和描述是否明确、无歧义是否枚举了可能的取值输出文档化10%工具返回的结果是什么格式包含哪些字段如何解读最差工具惩罚40%你所有工具中得分最低的那一个会严重拖累整体分数。这个权重分配是理解整个问题的关键。很多人会花大量时间优化他们觉得最重要的“旗舰”工具却忽略了一两个辅助性的、简单的工具。然而根据“最差工具惩罚”规则一个团队里有16个满分工具和1个不及格工具最终得到的可能只是一个平庸的总分。这就像木桶理论最短的那块板决定了容器的容量。在Glama的语境下那块短板占了40%的影响力。2.2 “最差工具惩罚”的杀伤力我们需要特别强调这个40%的权重因为它是绝大多数项目得分被拉低的核心原因。开发者常常犯一个错误他们认为工具的重要性与其代码复杂度成正比。因此他们会为执行复杂金融计算的工具编写详尽的文档却为一个简单的“获取当前时间”的工具只写一行注释。但在AI看来每一个工具都是一个独立的“技能”。当Claude在思考是否需要调用“获取当前时间”这个工具时它面临的困惑和调用“计算风险价值”工具时是一样的我需要传什么参数我会得到什么这个结果我该怎么用一个模糊的描述会让AI产生不确定性从而降低它调用该工具的意愿或导致错误调用。Glama的评分机制正是模拟了AI的这种“困惑度”并将团队中最让AI困惑的那个工具的问题放大到影响全局。3. 从不及格到优秀的实战改造案例理论讲完了我们来看一个血淋淋的“Before After”对比。这是从一个真实金融类MCP项目中摘取的工具定义。改造前得分约45/100mcp.tool() def risk_metrics(ticker: str, period: str “1y”) - str: “”“ Calculate risk metrics for a stock. ”“”看到这个定义你有什么感觉作为一个人类开发者你也许能猜出大概。但请切换到Claude的视角输入ticker是股票代码但有没有格式要求AAPL还是appleperiod是字符串但哪些值是合法的“1y”代表一年那“12m”行吗输出返回一个字符串。这个字符串是纯文本报告还是JSON包含哪些指标波动率夏普比率有没有具体的字段名使用场景“计算风险指标”——什么时候该用这个工具是在用户问“苹果公司风险高吗”的时候用还是在问“明天股价会涨吗”的时候用它和另一个叫technical_analysis的工具有什么区别这个描述留给AI的问题太多了。现在看改造后的版本改造后得分约88/100mcp.tool() def risk_metrics(ticker: str, period: str “1y”) - str: “”“ Calculate institutional-grade risk metrics: VaR at 95%/99%, Sharpe ratio, Sortino ratio, Beta vs SP 500, Max Drawdown. Use for risk assessment, not direction. Pair with technical_analysis() for a complete picture. Args: ticker: Stock symbol ( ‘AAPL‘, ‘TSLA‘, ‘SPY‘ ) period: ‘1mo‘, ‘3mo‘, ‘6mo‘, ‘1y‘ (default), ‘2y‘, ‘5y‘ Returns verdict: LOW/MODERATE/HIGH risk with SP comparison. ”“”我们来拆解这个优秀描述是如何得分的描述完整性25%第一句就明确列出了计算的具体指标VaR, Sharpe等建立了专业信任感。紧接着说明了使用场景“用于风险评估而非方向预测”以及如何与其他工具协作“与technical_analysis搭配使用”。这完美回答了“何时用”和“怎么用”的问题。参数清晰度25%Args部分不仅描述了参数是什么还枚举了所有可接受的值。ticker给出了例子period直接列出了所有选项并标明了默认值。这消除了AI的所有猜测。输出文档化10%Returns部分清晰地说明了输出结构一个包含“风险等级低/中/高”以及“与标普500对比”的裁决字符串。AI现在确切地知道会得到什么。规避最差工具惩罚这个工具本身已经做到了高度清晰不会成为那块短板。这个改造没有改动一行业务逻辑代码只改变了描述信息但带来的体验提升是指数级的。AI现在可以自信、准确地使用这个工具了。4. 提升Glama评分的六条黄金法则基于对评分标准和大量案例的分析我总结了六条可以立刻上手的实操法则。遵循它们你的工具描述质量将会有质的飞跃。4.1 明确命名输出内容糟糕示例“returns stock data”,“returns analysis results”优秀示例“Returns a JSON object with price, volume, P/E ratio, and 52-week high/low range.”核心要点不要使用概括性名词。AI需要知道具体字段名来理解和引用结果。如果你返回的是JSON直接列出关键字段如果是字符串描述其包含的信息模块。这直接提升了“输出文档化”的得分。4.2 说明工具间的选用逻辑糟糕示例两个工具描述互不关联优秀示例在risk_metrics的描述中写明“Use for risk assessment, not direction. Pair with technical_analysis() for a complete picture.”核心要点AI在拥有多个相似工具时会困惑。主动在你的工具描述中告诉它“什么时候用我”以及“我和隔壁工具的区别”。这相当于为AI绘制了一张技能地图极大地提升了工具调用的准确性和“描述完整性”。4.3 文档化参数的可选值糟糕示例period: strformat: str优秀示例period: ‘1mo‘, ‘3mo‘, ‘6mo‘, ‘1y‘ (default), ‘2y‘, ‘5y‘format: ‘json‘ (default) or ‘csv‘核心要点这是提升“参数清晰度”最有效的一步。尽可能枚举所有有效的参数值。对于字符串类型尤其重要这能防止AI传入非法值导致调用失败。对于布尔值或枚举类型这更是必须的。4.4 描述裁决或输出的结构糟糕示例“Returns a verdict.”优秀示例“Returns a verdict string in the format ‘BULLISH/NEUTRAL/BEARISH: [explanation]‘.”核心要点不要假设AI知道你的输出格式。明确说明返回的裁决、状态码或消息的结构。是简单的标签还是标签加解释是固定的几个选项还是自由文本清晰的输出结构描述能同时提升“输出文档化”和AI的结果解析能力。4.5 添加一个具体的调用示例优秀示例在描述末尾可以加一句“Example: Calling with ticker‘AAPL‘ and period‘1y‘ might return ‘LOW risk: Beta of 1.2 indicates slightly higher volatility than SP 500.‘“核心要点一个具体的例子胜过千言万语。它能为AI建立最直观的期望知道一个“好”的输入会得到什么样的“好”输出。这虽然不是评分细则里的明文规定但能显著改善AI的工具使用效果间接提升整体体验。4.6 像对待旗舰产品一样优化你最差的工具行动指南列出你MCP服务器中的所有工具用Glama的标准快速扫描一遍。找出那个描述最简单、最模糊的工具。它可能就是拉低你40%分数的罪魁祸首。花上15分钟为这个“短板”工具应用前面5条法则。通常修复这一个工具带来的分数提升比优化其他所有工具加起来还要大。5. 核心思维转变从人类文档到LLM提示词执行上述法则时最关键的是完成一次根本性的思维转变。过去我们写代码注释和API文档受众是其他人类开发者。我们默认对方有共同的背景知识能理解省略和概括。但现在你的工具描述的第一读者是Claude——一个没有上下文、严格按字面理解提示词的LLM。每一句描述都是一个微调提示词在训练AI如何与你的工具交互。旧的思维为人类写文档目标让同行快速理解功能概览。特点概括性强允许意会依赖常识。例子“计算股票指标。”新的思维为LLM写提示词目标让AI能做出无歧义的调用决策。特点具体、枚举、结构化、场景化。例子“计算机构级风险指标95%和99% VaR、夏普比率、索提诺比率、相对标普500的Beta值、最大回撤。用于评估资产风险水平而非预测价格走势。参数period仅接受‘1mo‘, ‘3mo‘, ‘6mo‘, ‘1y‘, ‘2y‘, ‘5y‘。返回‘低/中/高风险‘评级及与大盘的对比说明。”当你开始用“编写提示词”的思维来撰写工具描述时你会发现那些模糊的表述自然消失了取而代之的是精确的指令和约束。这种思维转变本身就足以让你的Glama评分提升20分以上。6. 一个下午的修复实战工作流现在让我们把理论付诸实践。以下是一个高效的工作流帮助你在一个下午约3-4小时内系统性地提升整个MCP服务器的Glama评分。6.1 第一步审计与诊断30分钟导出工具列表遍历你的MCP服务器代码列出所有被mcp.tool()装饰的函数。创建评分表用一个表格来记录包含列工具名、当前描述、预估问题参数模糊输出不明场景缺失、优先级。快速评分以Glama的四个维度为标尺快速为每个工具打个印象分。重点标记那些描述只有一行、参数全是str、输出为Any或str且无说明的工具。这些就是你的“短板”候选。6.2 第二步优先修复“最差工具”60分钟锁定目标从审计结果中找出1-2个描述最糟糕的工具。应用六法则法则6集中精力像写旗舰功能一样重写它的描述。法则3 4首先处理参数和返回值的明确化。枚举所有可能值定义清楚结构。法则1 2然后完善功能描述和使用场景说明区分于其他工具。法则5最后如果可能加上一个示例。完成修改确保这个工具的文档达到你心目中“完美”的标准。6.3 第三步批量优化其他工具90-120分钟分类处理将剩余工具按功能模块分组如数据查询类、计算类、工具类。模板化优化对同一类工具可以制定一个描述模板。例如所有数据查询工具都遵循“查询[某数据]参数为…返回包含…字段的JSON用于…场景”的格式。逐一过审按照模板快速优化每一个工具的描述。这个阶段追求的是“达标”而非“完美”确保没有明显漏洞。6.4 第四步交叉检查与一致性审查30分钟工具关联性检查检查在描述中提及其他工具如pair with X()时工具名是否正确逻辑是否合理。术语一致性确保整个项目中对同一概念如ticker的描述和示例保持一致。格式统一检查所有文档字符串的格式如Args:、Returns:的缩进和标点是否统一提升可读性。6.5 第五步测试与验证30分钟模拟对话测试如果你有Claude的开发环境可以创建一个简单的测试脚本让Claude使用你优化后的工具描述来尝试完成几个任务。观察它是否能正确选择工具、传递参数、理解输出。同行评审如果可能让另一个开发者快速阅读你的新描述看是否还有模糊之处。准备重新提交将更改提交到你的代码仓库。注意awesome-mcp-servers上的Glama徽章分数可能需要一段时间通常是下一次CI运行时才会更新。按照这个工作流你可以在一个下午的时间内将MCP服务器的工具描述质量从“AI友好度低”提升到“AI友好度高”从而显著提高Glama评分和工具的实际可用性。记住你优化的不是代码而是你与AI协作的接口。这个接口的清晰度直接决定了你的工具能否被充分、正确地利用。
MCP服务器Glama评分提升指南：从不及格到优秀的工具描述优化
发布时间：2026/5/28 5:27:09
1. 为什么你的MCP服务器在Glama上得分低于70以及如何用一个下午修复它如果你正在为Claude构建MCP服务器并且已经把它提交到了awesome-mcp-servers这个主要的工具发现平台那你很可能已经注意到了那个小小的Glama评分徽章。它静静地躺在你的项目旁边显示着一个数字——通常是55到70之间。这个分数就像一个隐形的门槛分数高的项目更容易获得开发者的信任和采用而分数低的则可能被默默滑过。我见过太多优秀的工具实现因为文档描述的问题被这个评分系统严重低估了其实际价值。今天我们就来彻底拆解Glama的TDQS评分机制。这不是什么黑盒魔法而是一套非常具体、可操作的评估标准。更重要的是修复它并不需要你重写核心逻辑或进行大规模重构。正如标题所说你完全可以在一个下午的时间里通过调整工具的描述方式将分数从不及格拉升到优秀线以上。关键在于一次思维模式的转变从“为人类编写文档”转向“为LLM编写提示词”。让我们深入看看这到底是怎么回事。2. Glama TDQS评分机制深度解析Glama的评分系统全称为“工具描述质量评分”它并非评估你代码的运行效率或功能复杂性而是专门评估你的工具描述信息对于像Claude这样的大型语言模型来说是否清晰、完整、可操作。你可以把它想象成一位极其严格的产品经理专门审查你提交给AI的“产品说明书”。2.1 评分组件与权重分配整个评分体系由四个核心组件构成每个都有明确的权重组件权重核心检查点描述完整性25%是否清晰说明了工具的输入、输出和核心使用场景参数清晰度25%每个参数的名称和描述是否明确、无歧义是否枚举了可能的取值输出文档化10%工具返回的结果是什么格式包含哪些字段如何解读最差工具惩罚40%你所有工具中得分最低的那一个会严重拖累整体分数。这个权重分配是理解整个问题的关键。很多人会花大量时间优化他们觉得最重要的“旗舰”工具却忽略了一两个辅助性的、简单的工具。然而根据“最差工具惩罚”规则一个团队里有16个满分工具和1个不及格工具最终得到的可能只是一个平庸的总分。这就像木桶理论最短的那块板决定了容器的容量。在Glama的语境下那块短板占了40%的影响力。2.2 “最差工具惩罚”的杀伤力我们需要特别强调这个40%的权重因为它是绝大多数项目得分被拉低的核心原因。开发者常常犯一个错误他们认为工具的重要性与其代码复杂度成正比。因此他们会为执行复杂金融计算的工具编写详尽的文档却为一个简单的“获取当前时间”的工具只写一行注释。但在AI看来每一个工具都是一个独立的“技能”。当Claude在思考是否需要调用“获取当前时间”这个工具时它面临的困惑和调用“计算风险价值”工具时是一样的我需要传什么参数我会得到什么这个结果我该怎么用一个模糊的描述会让AI产生不确定性从而降低它调用该工具的意愿或导致错误调用。Glama的评分机制正是模拟了AI的这种“困惑度”并将团队中最让AI困惑的那个工具的问题放大到影响全局。3. 从不及格到优秀的实战改造案例理论讲完了我们来看一个血淋淋的“Before After”对比。这是从一个真实金融类MCP项目中摘取的工具定义。改造前得分约45/100mcp.tool() def risk_metrics(ticker: str, period: str “1y”) - str: “”“ Calculate risk metrics for a stock. ”“”看到这个定义你有什么感觉作为一个人类开发者你也许能猜出大概。但请切换到Claude的视角输入ticker是股票代码但有没有格式要求AAPL还是appleperiod是字符串但哪些值是合法的“1y”代表一年那“12m”行吗输出返回一个字符串。这个字符串是纯文本报告还是JSON包含哪些指标波动率夏普比率有没有具体的字段名使用场景“计算风险指标”——什么时候该用这个工具是在用户问“苹果公司风险高吗”的时候用还是在问“明天股价会涨吗”的时候用它和另一个叫technical_analysis的工具有什么区别这个描述留给AI的问题太多了。现在看改造后的版本改造后得分约88/100mcp.tool() def risk_metrics(ticker: str, period: str “1y”) - str: “”“ Calculate institutional-grade risk metrics: VaR at 95%/99%, Sharpe ratio, Sortino ratio, Beta vs SP 500, Max Drawdown. Use for risk assessment, not direction. Pair with technical_analysis() for a complete picture. Args: ticker: Stock symbol ( ‘AAPL‘, ‘TSLA‘, ‘SPY‘ ) period: ‘1mo‘, ‘3mo‘, ‘6mo‘, ‘1y‘ (default), ‘2y‘, ‘5y‘ Returns verdict: LOW/MODERATE/HIGH risk with SP comparison. ”“”我们来拆解这个优秀描述是如何得分的描述完整性25%第一句就明确列出了计算的具体指标VaR, Sharpe等建立了专业信任感。紧接着说明了使用场景“用于风险评估而非方向预测”以及如何与其他工具协作“与technical_analysis搭配使用”。这完美回答了“何时用”和“怎么用”的问题。参数清晰度25%Args部分不仅描述了参数是什么还枚举了所有可接受的值。ticker给出了例子period直接列出了所有选项并标明了默认值。这消除了AI的所有猜测。输出文档化10%Returns部分清晰地说明了输出结构一个包含“风险等级低/中/高”以及“与标普500对比”的裁决字符串。AI现在确切地知道会得到什么。规避最差工具惩罚这个工具本身已经做到了高度清晰不会成为那块短板。这个改造没有改动一行业务逻辑代码只改变了描述信息但带来的体验提升是指数级的。AI现在可以自信、准确地使用这个工具了。4. 提升Glama评分的六条黄金法则基于对评分标准和大量案例的分析我总结了六条可以立刻上手的实操法则。遵循它们你的工具描述质量将会有质的飞跃。4.1 明确命名输出内容糟糕示例“returns stock data”,“returns analysis results”优秀示例“Returns a JSON object with price, volume, P/E ratio, and 52-week high/low range.”核心要点不要使用概括性名词。AI需要知道具体字段名来理解和引用结果。如果你返回的是JSON直接列出关键字段如果是字符串描述其包含的信息模块。这直接提升了“输出文档化”的得分。4.2 说明工具间的选用逻辑糟糕示例两个工具描述互不关联优秀示例在risk_metrics的描述中写明“Use for risk assessment, not direction. Pair with technical_analysis() for a complete picture.”核心要点AI在拥有多个相似工具时会困惑。主动在你的工具描述中告诉它“什么时候用我”以及“我和隔壁工具的区别”。这相当于为AI绘制了一张技能地图极大地提升了工具调用的准确性和“描述完整性”。4.3 文档化参数的可选值糟糕示例period: strformat: str优秀示例period: ‘1mo‘, ‘3mo‘, ‘6mo‘, ‘1y‘ (default), ‘2y‘, ‘5y‘format: ‘json‘ (default) or ‘csv‘核心要点这是提升“参数清晰度”最有效的一步。尽可能枚举所有有效的参数值。对于字符串类型尤其重要这能防止AI传入非法值导致调用失败。对于布尔值或枚举类型这更是必须的。4.4 描述裁决或输出的结构糟糕示例“Returns a verdict.”优秀示例“Returns a verdict string in the format ‘BULLISH/NEUTRAL/BEARISH: [explanation]‘.”核心要点不要假设AI知道你的输出格式。明确说明返回的裁决、状态码或消息的结构。是简单的标签还是标签加解释是固定的几个选项还是自由文本清晰的输出结构描述能同时提升“输出文档化”和AI的结果解析能力。4.5 添加一个具体的调用示例优秀示例在描述末尾可以加一句“Example: Calling with ticker‘AAPL‘ and period‘1y‘ might return ‘LOW risk: Beta of 1.2 indicates slightly higher volatility than SP 500.‘“核心要点一个具体的例子胜过千言万语。它能为AI建立最直观的期望知道一个“好”的输入会得到什么样的“好”输出。这虽然不是评分细则里的明文规定但能显著改善AI的工具使用效果间接提升整体体验。4.6 像对待旗舰产品一样优化你最差的工具行动指南列出你MCP服务器中的所有工具用Glama的标准快速扫描一遍。找出那个描述最简单、最模糊的工具。它可能就是拉低你40%分数的罪魁祸首。花上15分钟为这个“短板”工具应用前面5条法则。通常修复这一个工具带来的分数提升比优化其他所有工具加起来还要大。5. 核心思维转变从人类文档到LLM提示词执行上述法则时最关键的是完成一次根本性的思维转变。过去我们写代码注释和API文档受众是其他人类开发者。我们默认对方有共同的背景知识能理解省略和概括。但现在你的工具描述的第一读者是Claude——一个没有上下文、严格按字面理解提示词的LLM。每一句描述都是一个微调提示词在训练AI如何与你的工具交互。旧的思维为人类写文档目标让同行快速理解功能概览。特点概括性强允许意会依赖常识。例子“计算股票指标。”新的思维为LLM写提示词目标让AI能做出无歧义的调用决策。特点具体、枚举、结构化、场景化。例子“计算机构级风险指标95%和99% VaR、夏普比率、索提诺比率、相对标普500的Beta值、最大回撤。用于评估资产风险水平而非预测价格走势。参数period仅接受‘1mo‘, ‘3mo‘, ‘6mo‘, ‘1y‘, ‘2y‘, ‘5y‘。返回‘低/中/高风险‘评级及与大盘的对比说明。”当你开始用“编写提示词”的思维来撰写工具描述时你会发现那些模糊的表述自然消失了取而代之的是精确的指令和约束。这种思维转变本身就足以让你的Glama评分提升20分以上。6. 一个下午的修复实战工作流现在让我们把理论付诸实践。以下是一个高效的工作流帮助你在一个下午约3-4小时内系统性地提升整个MCP服务器的Glama评分。6.1 第一步审计与诊断30分钟导出工具列表遍历你的MCP服务器代码列出所有被mcp.tool()装饰的函数。创建评分表用一个表格来记录包含列工具名、当前描述、预估问题参数模糊输出不明场景缺失、优先级。快速评分以Glama的四个维度为标尺快速为每个工具打个印象分。重点标记那些描述只有一行、参数全是str、输出为Any或str且无说明的工具。这些就是你的“短板”候选。6.2 第二步优先修复“最差工具”60分钟锁定目标从审计结果中找出1-2个描述最糟糕的工具。应用六法则法则6集中精力像写旗舰功能一样重写它的描述。法则3 4首先处理参数和返回值的明确化。枚举所有可能值定义清楚结构。法则1 2然后完善功能描述和使用场景说明区分于其他工具。法则5最后如果可能加上一个示例。完成修改确保这个工具的文档达到你心目中“完美”的标准。6.3 第三步批量优化其他工具90-120分钟分类处理将剩余工具按功能模块分组如数据查询类、计算类、工具类。模板化优化对同一类工具可以制定一个描述模板。例如所有数据查询工具都遵循“查询[某数据]参数为…返回包含…字段的JSON用于…场景”的格式。逐一过审按照模板快速优化每一个工具的描述。这个阶段追求的是“达标”而非“完美”确保没有明显漏洞。6.4 第四步交叉检查与一致性审查30分钟工具关联性检查检查在描述中提及其他工具如pair with X()时工具名是否正确逻辑是否合理。术语一致性确保整个项目中对同一概念如ticker的描述和示例保持一致。格式统一检查所有文档字符串的格式如Args:、Returns:的缩进和标点是否统一提升可读性。6.5 第五步测试与验证30分钟模拟对话测试如果你有Claude的开发环境可以创建一个简单的测试脚本让Claude使用你优化后的工具描述来尝试完成几个任务。观察它是否能正确选择工具、传递参数、理解输出。同行评审如果可能让另一个开发者快速阅读你的新描述看是否还有模糊之处。准备重新提交将更改提交到你的代码仓库。注意awesome-mcp-servers上的Glama徽章分数可能需要一段时间通常是下一次CI运行时才会更新。按照这个工作流你可以在一个下午的时间内将MCP服务器的工具描述质量从“AI友好度低”提升到“AI友好度高”从而显著提高Glama评分和工具的实际可用性。记住你优化的不是代码而是你与AI协作的接口。这个接口的清晰度直接决定了你的工具能否被充分、正确地利用。
)
