Provides tools for interacting with SQLite databases, including inspecting database structure, getting table schemas, and executing SQL queries.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@unifiles-mcp read Sheet1 from sales.xlsx"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP server for unifiles - unified file operations library.
unifiles-mcp 是一个基于 MCP Python SDK 官方 SDK 构建的 Model Context Protocol (MCP) 服务器，为 AI 助手提供统一的文件操作能力。它使用官方的 FastMCP 高级接口，封装了 unifiles 库的功能，支持 Excel、PDF、Word、SQLite 等多种文件格式的读取、写入、查询和管理。
Related MCP server: MCP Filesystem Server
✅ 统一接口: 通过 MCP 协议提供标准化的文件操作接口
✅ 多格式支持: Excel (.xlsx, .xls), PDF (.pdf), Word (.docx), SQLite (.db, .sqlite)
✅ 类型安全: 完整的类型注解，基于 Pydantic V2
✅ 异步优先: 所有操作使用异步方式，提高性能
✅ LLM 友好: 优化的工具设计，减少调用次数
Python: 3.10+
操作系统: Windows 10+, Linux, macOS 10.14+
从源码安装（开发模式，含测试与类型检查等依赖）：
git clone https://github.com/Asheng008/unifiles-mcp.git
cd unifiles-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"仅安装运行依赖：
pip install -e .使用依赖锁文件安装（推荐用于生产环境）：
pip install -r requirements.txt若已发布到 PyPI：
pip install unifiles-mcp安装后可在终端直接运行：
unifiles-mcp或从代码启动：
from unifiles_mcp.main import mcp
if __name__ == "__main__":
mcp.run()服务器启动后，可通过 MCP 客户端连接使用。以下为常见客户端的配置方式。
在项目或用户配置的 .cursor/mcp.json 中加入（使用 PyPI 已发布包，需已安装 uv）：
{
"mcpServers": {
"unifiles-mcp": {
"command": "uvx",
"args": ["unifiles-mcp"]
}
}
}使用本地开发环境时，可改为指定 venv 中的 Python 与模块（将 D:\path\to\unifiles-mcp 替换为你的项目根目录）：
"unifiles-mcp": {
"command": "D:\\path\\to\\unifiles-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "unifiles_mcp.main"]
}在客户端的 MCP 配置文件中添加上述 command 与 args（或对应客户端的等价配置），指向 unifiles-mcp 或 python -m unifiles_mcp.main 即可。具体配置路径请参考各客户端的 MCP 文档。
# 1. 检查 Excel 文件结构
result = await excel_inspect_file(
file_path="data.xlsx",
include_preview=True,
preview_rows=3
)
# 返回：文件信息，包括所有工作表名称、列名和预览数据
# 2. 读取工作表内容
result = await excel_read_sheet(
file_path="data.xlsx",
sheet_name="Sheet1"
)
# 返回：JSON 格式的工作表数据# 1. 检查数据库结构
result = await sqlite_inspect_database(
db_path="database.db",
include_preview=True
)
# 返回：数据库信息，包括所有表的结构和数据预览
# 2. 获取表结构
result = await sqlite_get_schema(
db_path="database.db",
table_name="users"
)
# 返回：字段名到类型的映射
# 3. 执行查询
result = await sqlite_query(
db_path="database.db",
sql="SELECT * FROM users WHERE age > :age",
params={"age": 18}
)
# 返回：JSON 格式的查询结果# 提取所有页面
result = await pdf_extract_text(
file_path="document.pdf"
)
# 提取指定页面范围
result = await pdf_extract_text(
file_path="document.pdf",
page_range=(1, 5) # 第 1 到第 5 页
)# 1. 检查文档结构（上帝视角）
result = await word_inspect_document(
file_path="document.docx",
extract_images=False
)
# 返回：段落数、表格数、图片数等统计信息
# 2. 提取完整文本
result = await word_extract_text(
file_path="document.docx"
)
# 返回：文档完整文本（表格转为 Markdown）
# 3. 提取表格
result = await word_extract_tables(
file_path="document.docx",
output_format="md"
)
# 返回：Markdown 格式的表格
# 4. 写入文档
result = await word_write_document(
content="文档内容",
file_path="output.docx",
title="文档标题"
)excel_inspect_file - 检查 Excel 文件结构（"上帝视角"）
excel_read_sheet - 读取 Excel 工作表内容
pdf_extract_text - 提取 PDF 文本内容
word_inspect_document - 综合检查文档元素（"上帝视角"）
word_extract_text - 提取文档完整文本
word_extract_tables - 提取文档中的表格
word_extract_images - 提取文档中的图片
word_write_document - 写入 Word 文档
sqlite_inspect_database - 检查 SQLite 数据库（"上帝视角"）
sqlite_get_schema - 获取表结构
sqlite_query - 执行 SQL 查询
ping - 健康检查，返回 pong 表示服务运行中
# 激活虚拟环境
.\.venv\Scripts\Activate.ps1
# 使用 black 格式化代码
black src/
# 使用 ruff 检查代码
ruff check src/# 使用 mypy 进行类型检查
mypy src/unifiles_mcp/unifiles-mcp/
├── src/
│ └── unifiles_mcp/
│ ├── __init__.py
│ ├── main.py # MCP 服务器入口
│ ├── tools/ # MCP 工具
│ │ ├── __init__.py
│ │ ├── excel.py
│ │ ├── pdf.py
│ │ ├── word/ # Word 工具包
│ │ │ ├── __init__.py
│ │ │ ├── inspect.py
│ │ │ ├── extract.py
│ │ │ └── write.py
│ │ └── sqlite.py
│ └── utils/ # 工具函数
│ ├── __init__.py
│ ├── async_wrapper.py
│ └── validators.py
├── docs/ # 文档
│ ├── 01-API.md # API 文档
│ ├── 02-PYPI_RELEASE_CHECKLIST.md
│ └── 03-TESTING.md
├── .opencode/ # OpenCode 配置
│ └── rules/ # 项目规则
├── .cursor/ # Cursor IDE 配置（可选）
│ ├── commands/ # Cursor 命令
│ ├── rules/ # 项目规则
│ ├── skills/ # Cursor Skills
│ └── mcp.json # MCP 配置
├── LICENSE # MIT 许可证
├── publish_pypi.bat # Windows 发布脚本
├── publish_pypi.sh # Linux/macOS 发布脚本
├── requirements.txt # 生产依赖
├── requirements-dev.txt # 开发依赖（可选）
├── pyproject.toml # 项目配置
├── CHANGELOG.md # 更新日志
├── HISTORY.md # 对话与变更历史
├── AGENTS.md # AI Agent 开发规范
└── README.md # 本文档序号 | 文档 | 说明 |
01 | 详细的工具 API 说明和使用示例 | |
02 | 发布到 PyPI 前的检查与步骤 | |
03 | 测试指南（单元测试与集成测试） |
其他文档：
作者：Asheng (w62745@qq.com)
欢迎通过 Issues 或 Pull Request 参与贡献。
本项目采用 MIT License。
unifiles - 统一的文件操作库
MCP Python SDK - Model Context Protocol 官方 Python SDK
MCP 官方文档 - MCP Python SDK 完整文档
检查 Excel 文件结构。
返回包含所有 Sheet 名称、列头和前几行数据预览的摘要信息。 在决定读取哪个 Sheet 之前，请先使用此工具。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Excel 文件路径（支持相对路径和绝对路径） | |
| include_preview | No | 是否包含数据预览（默认 False，避免数据量大时性能问题） | |
| preview_rows | No | 如果 include_preview=True，每个工作表预览的行数（默认 3 行） |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, description carries full burden. It describes return values (sheet names, headers, preview) and mentions performance concern with include_preview. No side effects or destructive actions disclosed, but as a read-only operation, it's adequately transparent.
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?
Description is extremely concise with two sentences, front-loading the main purpose and usage guidance. No 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 low complexity and presence of output schema, the description fully covers purpose, usage, and parameter hints. It is complete for an inspection tool.
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 baseline 3. Description adds overall context about return values but does not enhance parameter descriptions beyond what schema provides.
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?
Description clearly states tool checks Excel file structure, returns sheet names, headers, and preview. It distinguishes from sibling tool 'excel_read_sheet' by advising use before reading a specific sheet.
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?
Explicitly instructs to use before deciding which sheet to read ('在决定读取哪个 Sheet 之前，请先使用此工具。'). However, it does not provide negative guidance or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取 Excel 工作表内容并返回 JSON 格式的数据。
支持读取单个工作表。如果数据量大，返回结果可能被截断。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Excel 文件路径（支持相对路径和绝对路径） | |
| sheet_name | No | 工作表名称或索引，None 表示读取第一个工作表 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It mentions truncation for large data, which is useful, but lacks other important details such as error handling (e.g., file not found), encoding, permissions, or whether the tool modifies the file. The description adds minimal value beyond basic purpose.
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 very concise with two sentences. The first sentence clearly states the purpose, and the second adds a key behavioral note about truncation. No unnecessary 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 presence of an output schema, return values are covered. However, the description lacks information about error scenarios (file not found, sheet not found), performance, and does not mention the sibling tool for inspection. It is adequate for basic use but not fully comprehensive.
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 input schema already documents both parameters adequately. The description does not add any extra information about parameters (e.g., format constraints, examples). Baseline score of 3 is appropriate as the description is neutral.
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 verb '读取' (read) and resource 'Excel 工作表内容' (Excel sheet content), with output format JSON. It specifies it supports reading a single sheet. However, it does not differentiate from the sibling tool 'excel_inspect_file', which might inspect structure rather than content.
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?
No guidance is provided on when to use this tool versus alternatives like excel_inspect_file. The only usage hint is about truncation for large data, but no explicit when-to-use or when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
从 PDF 文件中提取文本内容。
支持提取所有页面或指定页面范围的文本。页面之间用换行符分隔。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | PDF 文件路径（支持相对路径和绝对路径） | |
| page_range | No | 页码范围 (start, end)，1-based，None 表示提取所有页面。例如 [1, 5] 表示第 1 到第 5 页 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must cover behavioral aspects. It states extraction behavior and page separation but does not discuss edge cases like encrypted files, performance, or error handling.
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?
Two sentences, no filler, front-loaded with the core purpose. Every word contributes meaning.
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?
With output schema present and clear parameter descriptions, the description is largely complete. Could mention output format or limitations, but not essential given the output schema.
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 coverage is 100% and descriptions in schema are already informative. The tool description adds minimal extra context beyond what's in the schema (e.g., '1-based' for page_range).
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 extracts text from PDF files, with options for all pages or a range. The name 'pdf_extract_text' is specific and distinguishes it from siblings like 'word_extract_text'.
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 explains when to use it (PDF text extraction) but lacks explicit guidance on when not to use it or comparisons to alternatives. It indicates support for page ranges but no exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Health check endpoint. Returns 'pong' if server is running.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Description fully discloses behavior: checks server health and returns 'pong'. No annotations to contradict.
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?
Two concise sentences, front-loaded with purpose. Every word is necessary.
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 zero parameters and no annotations, description is fully adequate for a simple health check tool.
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?
No parameters exist; schema coverage is 100%. Description does not need to add param info.
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?
Clearly states it is a health check endpoint that returns 'pong' if server is running. No ambiguity.
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?
Implied usage is to verify server liveness. No siblings serve similar purpose, so no exclusions needed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
获取 SQLite 表结构（字段名到字段类型的映射）。
核心工具。LLM 写 SQL 前必须看 Schema。
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | SQLite 数据库文件路径（支持相对路径和绝对路径） | |
| table_name | Yes | 表名 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes it as a schema retrieval operation; read-only nature is implied but not explicitly stated. No contradictions.
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?
Very concise two-sentence description. Front-loaded with core purpose and critical usage hint. No 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?
With 2 well-described parameters and output schema available, the description provides necessary context (core tool, prerequisite). Complete for its purpose, though behavioral transparency could be enhanced.
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 coverage is 100% with each parameter having a basic description. The description adds no additional meaning beyond the schema, earning a baseline score.
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?
Clearly states it retrieves SQLite table schema (field name to type mapping). Identifies as a core tool and prerequisite for writing SQL, distinguishing it from sibling tools like sqlite_inspect_database and sqlite_query.
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?
Explicitly states 'LLM must see schema before writing SQL', providing clear context for when to use. Lacks explicit exclusions or alternatives but effectively implies use before queries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
检查 SQLite 数据库结构。
返回包含所有表名称、表结构和前几行数据预览的摘要信息。 在决定查询哪个表之前，请先使用此工具。
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | SQLite 数据库文件路径（支持相对路径和绝对路径） | |
| include_preview | No | 是否包含数据预览（默认 False，避免数据量大时性能问题） | |
| preview_rows | No | 如果 include_preview=True，每个表预览的行数（默认 3 行） |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool returns summary info and can include a preview, but does not mention error handling or authentication needs. The performance note is helpful, but more detail could be added.
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 three sentences, front-loaded with the core purpose, and each sentence contributes meaning. No 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 simplicity, the presence of an output schema, and the clear usage guidance, the description is complete. It covers what the tool does, when to use it, and key parameter considerations.
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 baseline is 3. The description reiterates the preview and performance aspects but adds little beyond the parameter descriptions themselves.
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 inspects SQLite database structure, returning table names, structures, and optional data preview. It explicitly advises using this tool before querying, distinguishing it from siblings like sqlite_query and sqlite_get_schema.
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 gives a direct usage hint: 'Before deciding which table to query, please use this tool.' It also mentions performance considerations for the preview parameter. While it doesn't explicitly exclude other tools, the context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
执行 SQL 查询并返回 JSON 格式的数据。
支持参数化查询，防止 SQL 注入。仅支持 SELECT 查询。
| Name | Required | Description | Default |
|---|---|---|---|
| db_path | Yes | SQLite 数据库文件路径（支持相对路径和绝对路径） | |
| sql | Yes | SQL 查询语句（仅支持 SELECT 查询） | |
| params | No | 查询参数（可选）。dict 用于 :name 占位符，list/tuple 用于 ? 占位符 |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It discloses security feature (parameterized queries) and query type restriction, but lacks details on error handling or read-only nature beyond the SELECT restriction.
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?
Two concise sentences, front-loaded with core purpose, no unnecessary words. Efficiently communicates key points.
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?
With output schema present, return format is covered. Description is sufficient for a simple read-only query tool, though it could mention reading from file system explicitly.
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 coverage is 100%, so parameters are well-documented in schema. Description adds only the security note about parameterized queries, which provides marginal additional value beyond schema.
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 executes SQL queries and returns JSON, explicitly limiting to SELECT queries. This distinguishes it from siblings like sqlite_get_schema.
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?
It explicitly restricts to SELECT queries and mentions parameterized queries for SQL injection prevention, providing clear usage boundaries. It could further contrast with sibling tools for when to use alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
提取 Word 文档中的图片。
返回包含每张图片元信息的列表，字段包括 filename、path、width、height、format、size_bytes。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Word 文档路径（支持相对路径和绝对路径，仅支持 .docx 格式） | |
| output_dir | No | 图片输出目录路径（默认 ./pics/） |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are available, so the description must cover behavioral traits. It fails to mention that only .docx files are supported (this is only in the schema), and it is unclear whether images are saved to the output directory or just metadata is returned. The description implies reading but lacks details on file system impact or error conditions.
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 very concise (two sentences) and front-loaded with the key action. Every sentence provides essential information without redundancy.
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?
For a simple tool with two parameters and an output schema, the description covers the basic purpose and output fields. However, it lacks usage guidance and behavioral transparency, which are needed for complete context. Score reflects adequacy with clear gaps.
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 coverage is 100%, with both parameters having descriptions. The tool description does not add additional meaning beyond the schema; it focuses on output fields. Baseline 3 is appropriate.
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 verb 'extract' and resource 'images from Word documents'. It distinguishes from sibling tools like word_extract_tables and word_extract_text by focusing on images. However, it does not explicitly differentiate itself from these siblings in the description.
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?
No guidance is provided on when to use this tool versus alternatives. It does not mention that for text or tables one should use the respective word_extract tools, nor does it state prerequisites or context for extraction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
提取 Word 文档中的所有表格。
支持返回 Markdown 格式或二维列表格式的表格数据。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Word 文档路径（支持相对路径和绝对路径，仅支持 .docx 格式） | |
| output_format | No | 输出格式：'md' 返回 Markdown 字符串，'list' 返回二维列表 | md |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description must disclose behavioral traits. It only states that it extracts all tables and supports two output formats, but does not mention whether the operation is non-destructive, error handling, or limitations (e.g., only .docx files are supported, though this is in the schema).
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 two sentences, front-loaded with the core purpose, and every sentence adds value. There is no unnecessary information, making it efficiently concise.
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?
The tool is simple, and the schema covers parameters and output. However, the description lacks details on return behavior, edge cases (e.g., no tables found), and error handling, leaving some contextual gaps despite having an output schema.
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 coverage is 100%, with both parameters having descriptions. The description adds minimal extra meaning beyond the schema, merely restating the output format options. Therefore, the baseline score of 3 is appropriate.
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 '提取 Word 文档中的所有表格' (Extract all tables from Word document), specifying the verb and resource. It distinguishes from sibling tools like word_extract_text (text extraction) and word_extract_images (image extraction) by focusing specifically on tables.
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 explicit guidance on when to use this tool versus alternatives. The usage context is implied by the tool's purpose, but no when-not or alternative recommendations are given, which is a gap for an AI agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
提取 Word 文档完整文本。
段落和表格按文档顺序输出，表格转换为 Markdown 格式。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Word 文档路径（支持相对路径和绝对路径，仅支持 .docx 格式） |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses output behavior: text extraction with table-to-Markdown conversion and document order preservation. With no annotations, this provides reasonable transparency for a read-only extraction tool, though it doesn't address potential limitations like large files or formatting loss.
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?
Two sentences with no wasted wording. First sentence states main purpose, second adds key details on output format and order, making it highly efficient.
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 simple single-parameter tool and existence of an output schema, the description sufficiently covers what the tool does and its output. Minor gaps (e.g., error handling, encoding) are acceptable for this low-complexity tool.
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 coverage is 100% and the parameter description is comprehensive, so the tool description does not need to add further parameter details. Baseline score of 3 is appropriate as no additional meaning is provided beyond the schema.
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?
Description clearly states it extracts complete text from Word documents and specifies output format (paragraphs and tables in order, tables as Markdown). It distinguishes itself from sibling tools like word_extract_images and word_extract_tables by focusing on full text extraction.
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?
No explicit guidance on when to use versus alternatives. While the output description implies its scope, it does not state exclusions or provide direct comparisons to sibling tools, leaving the agent to infer usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
综合检查 Word 文档元素。
提取文档中的段落、表格和图片信息，返回综合统计结果。 在决定读取哪个部分之前，请先使用此工具。
| Name | Required | Description | Default |
|---|---|---|---|
| file_path | Yes | Word 文档路径（支持相对路径和绝对路径，仅支持 .docx 格式） | |
| extract_images | No | 是否提取图片信息（默认 True） | |
| image_dir | No | 图片输出目录路径（默认 ./pics/） |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears responsibility. Describes behavior as inspecting and returning comprehensive statistics, but lacks details on side effects, permissions, or performance. Adequate but not exhaustive.
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?
Three sentences, each adding value: purpose, content, usage guidance. Front-loaded and no wasted words. Efficient structure.
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 3 parameters and existence of output schema, description covers purpose, usage guidance, and basic behavior. Could mention output schema structure or error handling, but still fairly complete for an inspection tool.
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 covers 100% of parameters with descriptions. Description does not add extra meaning beyond what schema provides, so baseline score of 3 applies.
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?
Description clearly states verb 'inspect' and resource 'Word document elements', listing specific extractables (paragraphs, tables, images). Distinguishes from sibling tools by advising to use this before reading a specific part, making it a meta-inspection tool.
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?
Explicitly says 'Before deciding which part to read, please use this tool first', providing clear context when to use. Does not give negative examples but the guidance is distinct enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
将内容写入 Word 文档。
创建新的 Word 文档并写入内容。如果提供了标题，会将标题作为文档标题添加。
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | 要写入的文本内容 | |
| file_path | Yes | 输出 Word 文档路径 | |
| title | No | 可选的文档标题 |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description carries full burden. It only mentions creating a document and adding title, but fails to disclose whether file_path overwrites existing files, required permissions, or output behavior.
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?
Two sentences, zero waste. Purpose is front-loaded and efficiently conveyed.
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?
Adequate for a simple write tool with output schema, but misses behavioral details like file overwrite handling, making it slightly incomplete.
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 coverage is 100%, so baseline is 3. Description adds minimal extra meaning (title becomes document title), but doesn't elaborate beyond schema.
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 '将内容写入 Word 文档' (write content to Word document) and specifies it creates a new document, differentiating it from read-only siblings like word_extract_text.
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 does not explicitly guide when to use this tool versus alternatives. While the name suggests writing, no mention of contexts like overwrite behavior or file existence is given.
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. Dates show when Glama detected each change.
v0.1.4excel_inspect_fileexcel_read_sheetpdf_extract_textpingsqlite_get_schemasqlite_inspect_databasesqlite_queryword_extract_imagesword_extract_tablesword_extract_textword_inspect_documentword_write_documentEach tool targets a specific file type and action (e.g., inspect vs read for Excel, extract vs write for Word), with no overlapping purposes. The ping tool is distinct. Even complementary tools like sqlite_inspect_database and sqlite_get_schema have clear, separate roles.
Tools use a consistent filetype_verb_noun pattern (e.g., excel_inspect_file, word_extract_text). The verb choice varies across file types (inspect, read, get, query, extract, write), but within each group the pattern is predictable. The lone ping tool lacks a prefix, breaking the pattern slightly.
12 tools is well within the ideal range. Each file type has a focused set (Excel:2, PDF:1, SQLite:3, Word:5) that covers essential operations without overloading the server. No tool feels redundant or unnecessary.
The server covers inspection, reading, and extraction for Excel, PDF, SQLite, and Word, plus Word write. Missing write operations for Excel, PDF, and SQLite, but the server's focus seems read-only. There is no tool for CSV or other formats, but the current scope is reasonably complete.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
An agent-first office suite Claude & ChatGPT read and write over one MCP URL.
Persistent file storage for AI agents via MCP and curl. Upload, download, and version files.
Browse and manage files in your Moxt AI workspace from any MCP client.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Asheng008/unifiles-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
