Un servicio MCP que permite a la IA local seguir consultando a modelos de lenguaje grandes (LLM) remotos cuando se enfrenta a problemas de programación complejos.
El repositorio actual corresponde a la versión "lista para uso a largo plazo", que ya ha completado estas capacidades clave:
Consultas de múltiples turnos e informes de progreso
Sincronización de archivos sync_context
Carga automática de código/archivos de configuración convertidos a texto
Aislamiento de sesiones (session_id)
Persistencia del historial, bloqueo de archivos y escritura atómica
Resumen automático del historial
Recorte de la ventana de contexto
Esta actualización principal se centra en:
Corrección del problema donde el historial "resucitaba" tras ser borrado y reiniciado
Adición de aislamiento de sesiones mediante session_id para evitar que el contexto se mezcle entre diferentes problemas
Integración de configuraciones reales y funcionales como AURAI_TEMPERATURE, AURAI_MAX_ITERATIONS y AURAI_LOG_LEVEL
Envío real de project_info y respuestas complementarias al asesor superior
Adición de bloqueo de archivos de historial y escritura atómica para reducir el riesgo de corrupción del historial por concurrencia
Adición de resumen automático del historial para evitar que las sesiones largas se vuelvan demasiado pesadas
Adición de recorte de ventana de contexto; AURAI_CONTEXT_WINDOW ahora tiene efecto real
sync_context ahora admite la conversión automática de archivos de texto (código/configuración) a formato enviable, sin necesidad de copiar manualmente a .txt
Reescritura del README, la guía de instalación y el manual de usuario, colocando los pasos de instalación en una posición más destacada
Si es la primera vez que visitas este repositorio, los dos puntos más importantes son:
Lee primero la "Guía de instalación" a continuación
Los archivos de código ahora se pueden pasar directamente a sync_context
Related MCP server: session-coord-mcp
Este MCP es adecuado para su uso en Claude Code o cualquier otro cliente MCP que admita el modo stdio.
Escenarios típicos:
La IA local ya lo ha intentado, pero el problema sigue sin resolverse
Necesidad de enviar errores, código, documentación y configuraciones al "asesor superior"
Deseo de convertir una investigación compleja en un proceso de múltiples turnos: "Preguntar -> Ejecutar -> Informar -> Siguiente paso"
consult_aurai
Herramienta de consulta principal. Envía problemas, fragmentos de código, contexto y soluciones intentadas para obtener el análisis y las sugerencias del asesor superior.
sync_context
Sincroniza el contexto de código y documentación.
Ahora no solo admite .txt/.md, sino que convierte automáticamente archivos de texto como .py/.js/.ts/.json/.yaml/.toml/.ini en contenido de texto adecuado para el envío.
report_progress
Informa de los resultados de la ejecución al asesor superior para continuar con la siguiente iteración.
get_status
Consulta el estado de la sesión actual, el número de registros históricos y las rutas de los archivos de modelo e historial.
Para pasos de instalación más detallados, consulta:
A continuación, se presenta el flujo de instalación más común.
# 需要 Python 3.10+
python --version
# 进入仓库目录
cd G:\codex\mcp-aurai-serverpython -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"claude mcp add --scope user --transport stdio aurai-advisor ^
--env AURAI_API_KEY="your-api-key" ^
--env AURAI_BASE_URL="https://api.example.com/v1" ^
--env AURAI_MODEL="gpt-4o" ^
-- "G:\codex\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"Nota:
AURAI_BASE_URL debe ser una dirección de interfaz compatible con OpenAI
La versión actual solo conserva el método custom, ya no se utiliza el antiguo AURAI_PROVIDER
--scope user indica que estará disponible en todos los proyectos, lo cual es más conveniente
claude mcp list
pytestResultado esperado:
claude mcp list muestra aurai-advisor
pytest pasa correctamente
consult_aurai(
problem_type="runtime_error",
error_message="启动时报 KeyError: api_key",
code_snippet="config = load_config()\napi_key = config['api_key']",
context={
"file_path": "src/config.py",
"terminal_output": "Traceback ...",
}
)sync_context(
operation="incremental",
files=["src/main.py", "config/settings.json", "README.md"],
project_info={
"project_name": "My Project",
"tech_stack": "Python + FastAPI"
}
)
consult_aurai(
problem_type="runtime_error",
error_message="请结合已同步文件帮我排查启动失败"
)Nota:
Ya no es necesario copiar manualmente main.py a main.txt
Los archivos de código de texto se convertirán automáticamente a texto para su envío
Los archivos binarios serán omitidos
consult_aurai(
problem_type="runtime_error",
error_message="问题 A",
session_id="issue-a"
)
consult_aurai(
problem_type="design_issue",
error_message="问题 B",
session_id="issue-b"
)Esto evita que diferentes problemas se mezclen entre sí.
.md, .markdown, .mdx
.txt
Varios archivos de texto de código y configuración, por ejemplo:
.py .js .ts .tsx
.json .yaml .yml .toml
.ini .cfg .env
.java .go .rs .cpp .cs
Archivos que no son .txt/.md pero cuyo contenido es texto
Se generará automáticamente un nombre de envío .txt o .md
Se incluirá la "ruta del archivo original" y el "nombre de envío convertido automáticamente" antes del contenido
Imágenes
Archivos comprimidos
Audio y video
Archivos ejecutables
Contenido claramente binario
Si un lote de archivos contiene tanto código como imágenes:
El código se subirá normalmente
Las imágenes se registrarán en skipped_files
La sincronización completa seguirá siendo exitosa
Variable | Descripción |
| Clave de API |
| Dirección de interfaz compatible con OpenAI |
| Nombre del modelo |
Variable | Descripción | Valor predeterminado |
| Temperatura |
|
| Número máximo de iteraciones |
|
| Límite de registros históricos por sesión |
|
| Tamaño total de la ventana de contexto |
|
| Límite de tamaño para mensajes de archivos grandes |
|
| Longitud máxima de salida |
|
| Nivel de registro |
|
| ¿Habilitar persistencia del historial? |
|
| Ruta predeterminada del archivo de historial |
|
| Tiempo de espera de bloqueo del archivo (segundos) |
|
| ¿Habilitar resumen del historial? |
|
| Rondas originales recientes a conservar tras el resumen |
|
| Umbral de registros originales para activar el resumen |
|
Cada session_id tiene su propio historial
Si no se pasa ninguno, se utiliza default
Las diferentes sesiones se guardan en archivos de historial distintos para evitar mezclas
El historial antiguo se comprime automáticamente en un "resumen del historial"
Se intenta conservar intactas las últimas rondas y el último sync_context
Esto reduce el uso de contexto, dejando espacio para el problema actual
Se prioriza la conservación de las instrucciones del sistema
Se prioriza la conservación del último sync_context
Se intenta conservar las rondas de historial más recientes
Si es necesario, se reduce automáticamente la longitud de la salida actual para evitar exceder la ventana total
Se utilizan archivos de bloqueo al guardar el historial para evitar corrupciones por concurrencia
La escritura se realiza mediante archivos temporales que luego se reemplazan, evitando archivos JSON incompletos
pytestLos puntos clave cubiertos por la rama principal actual incluyen:
Borrado y persistencia del historial
Aislamiento de sesiones
Carga automática con conversión de texto
Bloqueo de historial y escritura atómica
Resumen del historial
Recorte de la ventana de contexto
Las versiones antiguas requerían convertir manualmente a .txt. La versión actual ya admite la conversión automática de archivos de texto.
Si aún no lo recibe, verifica primero:
Si la ruta del archivo existe
Si el archivo es binario
Los campos uploaded_files / skipped_files en la respuesta de sync_context
Si deseas un aislamiento total, pasa un session_id diferente para cada problema.
Es el resumen del historial trabajando. El historial antiguo se comprime en un acta; no se ha perdido, simplemente se ha convertido en un "acta de reunión" que ahorra más contexto.
请求上级AI的指导（支持交互对齐机制与多轮对话）
这是核心工具，当本地AI遇到编程问题时调用此工具获取上级AI的指导建议。
🔗 相关工具
sync_context：需要上传文档或代码时使用
📄 上传文章、说明文档（.md/.txt）
💻 上传代码文件（避免内容被截断） ⭐ 重要
将 .py/.js/.json 等代码文件复制为 .txt 后上传
report_progress：执行上级 AI 建议后，使用此工具报告进度并获取下一步指导
get_status：查看当前对话状态、迭代次数、配置信息
💡 重要提示：避免内容被截断
如果 code_snippet 或 context 内容过长，请使用 sync_context 上传文件：
# 步骤 1：将代码文件复制为 .txt
shutil.copy('script.py', 'script.txt')
# 步骤 2：上传文件
sync_context(operation='incremental', files=['script.txt'])
# 步骤 3：告诉上级顾问文件已上传
consult_aurai(
error_message='请审查已上传的 script.txt 文件'
)优势：
✅ 避免代码在 context 或 answers_to_questions 字段中被截断
✅ 利用文件读取机制，完整传递内容
✅ 支持任意大小的代码文件
系统会自动检测，但你也可以手动控制：
自动清空：当上一次对话返回 resolved=true 时，系统会自动清空历史
手动清空：如果你要讨论一个完全不同的新问题，设置 is_new_question=true
何时设置 is_new_question=true？
[OK] 切换到完全不相关的项目/文件
[OK] 之前的问题已解决，现在遇到全新的问题
[OK] 发现上下文混乱，想重新开始
不要在同一个问题的多轮对话中使用
不要期待一次成功：上级顾问可能会认为信息不足，返回反问问题
仔细阅读 questions_to_answer 中的每个问题
主动搜集信息（读取文件、检查日志、运行命令）
再次调用 此工具，将答案填入 answers_to_questions 参数
必须提供：
problem_type：问题类型（runtime_error/syntax_error/design_issue/other）
error_message：清晰描述问题或错误
context：相关上下文（代码片段、环境信息、已尝试的方案）
code_snippet：相关代码（如果有）
必须提供：
answers_to_questions：对上级顾问反问的详细回答
保持其他参数不变（除非有新信息）
禁止瞎编：如果不知道答案，诚实说明"未找到相关信息"
禁止臆测：不要在没有证据的情况下假设解决方案
提供具体证据（文件路径、日志内容、错误堆栈）
{
"status": "need_info",
"questions_to_answer": ["问题1", "问题2"],
"instruction": "请搜集信息并再次调用"
}{
"status": "success",
"analysis": "问题分析",
"guidance": "解决建议",
"action_items": ["步骤1", "步骤2"],
"resolved": false // 是否已完全解决
}当 resolved=true 时，对话历史会自动清空，下次查询将开始新对话。
系统会自动检测新问题：
如果上一次对话的 resolved=true，下次调用 consult_aurai 时会自动清空历史
保证每个独立问题都有干净的上下文，避免干扰
如果你想强制开始一个新对话，可以设置 is_new_question=true：
效果：立即清空所有之前的对话历史
后果：上级AI将无法看到之前的任何上下文
使用场景：
之前的对话已完全无关
想重新开始讨论一个全新的问题
发现上下文混乱，想重置
示例：
# 第一次咨询（问题A）
consult_aurai(problem_type="runtime_error", error_message="...")
# 继续讨论问题A...
consult_aurai(answers_to_questions="...")
# 切换到问题B（标注为新问题，清空历史）
consult_aurai(
problem_type="design_issue",
error_message="...",
is_new_question=True # [注意] 会清空之前关于问题A的所有对话
)| Name | Required | Description | Default |
|---|---|---|---|
| problem_type | Yes | 问题类型: runtime_error, syntax_error, design_issue, other | |
| error_message | Yes | 错误描述 | |
| code_snippet | No | 相关代码片段 | |
| context | No | 上下文信息（支持 JSON 字符串或字典，会自动解析） | |
| attempts_made | No | 已尝试的解决方案 | |
| answers_to_questions | No | 对上级顾问反问的回答（仅在多轮对话时使用） | |
| is_new_question | No | [重要] 是否为新问题（新问题会清空之前的所有对话历史，确保干净的上下文） |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure and excels. It describes the multi-round interaction protocol (status='need_info' triggers follow-up calls), honest principle requirements (no fabrication), automatic history clearing when resolved=true, consequences of is_new_question (clears all prior context), and response formats. It adds rich context beyond what the input schema provides.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is comprehensive but overly long and not front-loaded. While it contains valuable information, it includes extensive formatting (markdown, code blocks, emojis) and repetitive sections (e.g., multiple warnings about truncation, redundant explanations of is_new_question). Some content could be condensed without losing clarity, making it less efficient than ideal.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (multi-round interaction, 7 parameters), no annotations, and the presence of an output schema, the description is exceptionally complete. It covers purpose, usage, behavioral protocols, parameter guidance, sibling tool relationships, and response handling. The output schema existence means return values needn't be explained, and the description fully compensates for the lack of annotations with detailed operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining parameter usage in context: it specifies which parameters are required for first calls (problem_type, error_message, context, code_snippet) vs. follow-up calls (answers_to_questions), provides examples for code_snippet/context handling with sync_context, and clarifies the impact of is_new_question. However, it doesn't add deep semantic nuance beyond the schema's descriptions for all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the tool's purpose: '请求上级AI的指导' (request guidance from a higher-level AI) and '当本地AI遇到编程问题时调用此工具获取上级AI的指导建议' (call this tool when the local AI encounters programming problems to get guidance from a higher-level AI). It clearly distinguishes from siblings by explaining this is the '核心工具' (core tool) for obtaining AI guidance, while sibling tools handle context synchronization, progress reporting, and status checking.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides extensive usage guidelines, including when to use this tool ('当本地AI遇到编程问题时'), when to use sibling tools instead (e.g., use sync_context for uploading files to avoid truncation, report_progress after executing suggestions), and explicit alternatives. It also details when to set parameters like is_new_question and provides scenarios for manual vs. automatic context clearing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取当前状态
返回当前对话状态、迭代次数、配置信息等。
返回内容：conversation_history_count（对话历史数量）、max_iterations（最大迭代次数）、max_history（最大历史条数）、provider（AI提供商）、model（模型名称）
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It describes what the tool returns (conversation state, iteration count, configuration) and lists specific return fields, which adds useful context about the tool's behavior. However, it doesn't mention whether this is a read-only operation, if it requires authentication, or any rate limits—important details for a status-checking tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first line states the purpose clearly, followed by details on return content. The use of a separator (---) and bullet points for return fields improves readability. However, the inclusion of both Chinese and English text slightly reduces efficiency, and some redundancy exists (e.g., stating return content in two ways).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no annotations, but has an output schema), the description is reasonably complete. It explains what the tool does and details the return values, which compensates for the lack of annotations. Since an output schema exists, the description doesn't need to fully explain return values, but it still provides a helpful overview. For a status-retrieval tool, this is adequate though not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage (empty schema), so the baseline is 4 as per the rules for zero parameters. The description appropriately doesn't discuss parameters since none exist, and it focuses on the return values instead, which is correct given the context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '获取当前状态' (get current status) and specifies it returns conversation state, iteration count, and configuration information. This is a specific verb+resource combination that distinguishes it from sibling tools like consult_aurai, report_progress, and sync_context, which appear to perform different functions. However, it doesn't explicitly contrast with siblings beyond implying different functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention any prerequisites, appropriate contexts, or comparisons with sibling tools like consult_aurai or report_progress. The agent must infer usage from the purpose alone, which is insufficient for optimal tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
报告执行进度，请求下一步指导
在执行了上级AI的建议后，调用此工具报告结果，获取下一步指导。
使用场景：执行上级 AI 建议后，报告执行结果并获取后续指导 参数：actions_taken（已执行的行动）、result（success/failed/partial）、new_error（新错误）、feedback（反馈）
| Name | Required | Description | Default |
|---|---|---|---|
| actions_taken | Yes | 已执行的行动 | |
| result | Yes | 执行结果: success, failed, partial | |
| new_error | No | 新的错误信息 | |
| feedback | No | 执行反馈 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes the tool's purpose and workflow (reporting progress and requesting guidance), though it doesn't specify technical details like response format, rate limits, or authentication requirements. However, it clearly communicates the tool's interactive nature and expected usage pattern.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It opens with a clear purpose statement, provides usage guidelines, and includes a formatted section with usage scenarios and parameters. Every sentence serves a purpose with no redundancy or wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (4 parameters, interactive workflow) and the presence of an output schema (which handles return values), the description is largely complete. It covers purpose, usage context, and parameters adequately. The main gap is lack of behavioral details like error handling or response structure, but the output schema mitigates this.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters thoroughly. The description lists parameters in a section but doesn't add meaningful semantic context beyond what's in the schema (e.g., explaining how 'result' influences guidance or what constitutes good 'feedback'). This meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('报告执行进度' - report execution progress, '请求下一步指导' - request next-step guidance) and distinguishes it from siblings like consult_aurai (consultation), get_status (status retrieval), and sync_context (context synchronization). It explicitly defines the tool's role in reporting results after executing superior AI suggestions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage guidelines: '在执行了上级AI的建议后，调用此工具报告结果，获取下一步指导' (After executing superior AI suggestions, call this tool to report results and get next-step guidance). It clearly defines when to use this tool (post-execution reporting) versus alternatives like consult_aurai (for consultation before execution) or get_status (for status checking without guidance).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
同步代码上下文（支持上传 .md 和 .txt 文件，避免内容被截断）
在第一次调用或上下文发生重大变化时使用，让上级AI了解当前项目的整体情况。
🎯 典型使用场景
sync_context(
operation='full_sync',
files=['文章.md'],
project_info={
'task': 'article_review',
'target_platform': 'GLM Coding 知识库'
}
)
consult_aurai(
problem_type='other',
error_message='请评审以下投稿文章...',
context={'请查看已上传的文章文件': '已通过 sync_context 上传'}
)# 问题：代码太长，在 context 字段中可能被截断
# 解决：将代码转换为 .txt 文件后上传
import shutil
# 步骤 1：将代码文件复制为 .txt
shutil.copy('src/main.py', 'src/main.txt')
# 步骤 2：上传文件
sync_context(
operation='incremental',
files=['src/main.txt'],
project_info={
'description': '需要调试的代码',
'language': 'Python'
}
)
# 步骤 3：告诉上级顾问文件已上传
consult_aurai(
problem_type='runtime_error',
error_message='请审查已上传的 src/main.txt 文件，帮我找出bug',
context={
'file_location': '已通过 sync_context 上传',
'expected_behavior': '应该输出...',
'actual_behavior': '实际输出...'
}
)优势：
✅ 避免代码在 context 或 answers_to_questions 字段中被截断
✅ 利用 sync_context 的文件读取机制，完整传递内容
✅ 上级顾问可以完整读取代码文件
sync_context(
operation='full_sync',
files=['README.md', 'docs/说明文档.md'],
project_info={
'project_name': 'My Project',
'tech_stack': 'Python + FastAPI'
}
)files 参数只支持 .txt 和 .md 文件！
[OK] 支持：README.md, docs.txt, notes.md 等文本和Markdown文件
不支持：.py, .js, .json, .yaml 等代码文件
full_sync: 完整同步，适合首次调用或项目重大变更
incremental: 增量同步，适合添加新文件或更新
clear: 清空对话历史
当 project_info 中的单个字段超过 800 tokens 时，会自动：
缓存到临时文件
在对话历史中记录文件路径
发送给上级AI时仍会读取完整内容
operation: 操作类型（full_sync/incremental/clear）
files: 文件路径列表，只能是 .txt 或 .md 文件
project_info: 项目信息字典，可包含任意字段
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | 操作类型: full_sync（完整同步）, incremental（增量添加）, clear（清空历史） | |
| files | No | **⚠️ 只支持 .txt 和 .md 文件！** 如需上传代码文件（.py/.js/.json等），必须先复制为 .txt。示例: shutil.copy('script.py', 'script.txt') 然后传 files=['script.txt']。文件路径列表（支持 JSON 字符串或列表，会自动解析） | |
| project_info | No | 项目信息字典，可包含项目名称、技术栈、任务描述等任意字段（支持 JSON 字符串或字典，会自动解析） |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: file type restrictions (.txt and .md only), token optimization (caching for fields >800 tokens), and the three operation modes (full_sync, incremental, clear) with their purposes. However, it doesn't mention potential side effects like whether files are stored persistently, if there are rate limits, or authentication requirements, leaving some gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with sections for typical scenarios, notes, and parameter explanations, but it is overly verbose. The extensive code examples and scenario details could be condensed; not every sentence earns its place as some repetition occurs (e.g., file restrictions mentioned multiple times). It's front-loaded with the core purpose, but the length may reduce scanability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (mutation with file handling) and rich schema (100% coverage, output schema exists), the description is highly complete. It covers purpose, usage guidelines, behavioral traits, parameter semantics with examples, and operational details. The output schema handles return values, so the description appropriately focuses on input and behavior, leaving no significant gaps for agent understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all parameters. The description adds significant value beyond the schema by explaining the rationale behind file restrictions (to avoid truncation), providing concrete usage examples with code snippets, and detailing token optimization behavior. However, it doesn't fully explain the semantics of 'project_info' beyond stating it can contain arbitrary fields, missing guidance on typical or required fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '同步代码上下文（支持上传 .md 和 .txt 文件，避免内容被截断）' - to sync code context by uploading .md and .txt files to avoid truncation. It specifies the verb (sync/upload), resource (code context via files), and distinguishes from siblings by focusing on file-based context management rather than consultation, status checking, or progress reporting.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: '在第一次调用或上下文发生重大变化时使用' (use on first call or when context changes significantly). It includes detailed scenarios (article review, code upload, project initialization) with concrete examples and contrasts with alternatives by noting that code should be uploaded here instead of placed in 'context' or 'answers_to_questions' fields of other tools to avoid truncation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.2.0consult_auraiget_statusreport_progresssync_contextScored across 4 tools
Each tool has a distinct, non-overlapping purpose: consult_aurai for core advice, sync_context for file uploads, report_progress for progress updates, and get_status for status checks. The descriptions clearly differentiate their roles, with no ambiguity in when to use each tool.
All tool names follow a consistent snake_case pattern with clear verb_noun structures: consult_aurai, sync_context, report_progress, get_status. This uniformity makes the set predictable and easy to understand for an agent.
With 4 tools, this server is well-scoped for its purpose of providing AI-guided problem-solving. Each tool serves a specific function in the workflow (consult, sync, report, status), and there are no extraneous or missing tools for the domain.
The tool set fully covers the intended workflow: initiating consultations (consult_aurai), providing context (sync_context), reporting progress (report_progress), and checking status (get_status). There are no gaps; agents can handle the entire lifecycle from problem submission to resolution.
MCP server for AI dialogue using various LLM models via AceDataCloud
Hosted MCP server connecting claude.ai, ChatGPT and other AI apps to your own computer
An MCP server that gives your AI access to the source code and docs of all public github repos
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
