Un servidor de Model Context Protocol (MCP) construido con FastMCP (v3.x) y Python, diseñado para proporcionar herramientas y recursos para el seguimiento de gastos a clientes compatibles con MCP como Claude Desktop y el MCP Inspector.
Python: 3.10+ (probado con Python 3.14)
uv: Instalador y resolvedor de paquetes de Python rápido (astral.sh/uv)
Node.js: v22.x o v24.x (LTS) — Requerido para la interfaz de usuario de MCP Inspector
Claude Desktop (opcional): Para probar herramientas directamente dentro de Claude
Related MCP server: Math Addition MCP Server
# Initialize uv project (if starting fresh)
uv init .
# Install FastMCP
uv add fastmcpEl MCP Inspector (@modelcontextprotocol/inspector) requiere Node.js v22.19.0+ o v24+. Si se usa nvm-windows:
nvm install lts
nvm use 24Instale el inspector globalmente o permita que npx lo obtenga:
npm install -g @modelcontextprotocol/inspectorPara lanzar la interfaz web del MCP Inspector con recarga en caliente:
uv run fastmcp dev inspector main.pyMantenga esta ventana de terminal abierta.
La consola mostrará una URL local con un token de autenticación:
MCP Inspector Web is up and running at:
http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=<token>Abra ese enlace en su navegador para probar herramientas, inspeccionar esquemas y ver registros de solicitudes/respuestas en tiempo real.
Para ejecutar el servidor MCP en modo de entrada/salida estándar:
uv run fastmcp run main.py(o uv run python main.py)
En Windows, la configuración de Claude Desktop se almacena en:
%APPDATA%\Claude\claude_desktop_config.json(Ruta completa: C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)
Agregue la definición de expense-server bajo mcpServers.
Nota: En Windows, las aplicaciones GUI como Claude Desktop a menudo no heredan el
PATHdel shell. Especifique siempre la ruta absoluta auv.exe.
{
"mcpServers": {
"expense-server": {
"command": "C:\\Users\\pyash\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
"args": [
"run",
"--directory",
"d:\\expense-tracker-mcp-server",
"fastmcp",
"run",
"main.py"
]
}
}
}Cierre completamente Claude Desktop (asegúrese de que se cierre desde la bandeja del sistema de Windows cerca del reloj).
Vuelva a abrir Claude Desktop.
Verifique en Configuración > Desarrollador que expense-server esté conectado.
main.py)Tool | Parameters | Description |
|
| Lanza |
|
| Suma dos números y devuelve la suma. |
Unknown command "main.py". Available commands: inspector, apps.En FastMCP 3.x, fastmcp dev es un grupo de comandos. Use fastmcp dev inspector main.py en lugar de fastmcp dev main.py.
node:util does not provide an export named 'styleText'Node.js es anterior a v20.12. Actualice a Node v22+ o v24+ mediante nvm install lts && nvm use 24.
Cannot find native binding (npm optional dependencies bug)Caché de npx corrupta por cambiar de versiones de Node. Ejecute:
npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm install -g @modelcontextprotocol/inspectorAdd a new expense entry to the database.
| Name | Required | Description | Default |
|---|---|---|---|
| date | Yes | ||
| note | No | ||
| amount | Yes | ||
| category | Yes | ||
| subcategory | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It states that an entry is added, but does not disclose validation behavior, duplicate handling, side effects, required-field enforcement, or what happens after a successful add.
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 a single, direct sentence with virtually no filler. It could be considered slightly under-specified, but as far as conciseness and structure go, it is efficient and easy to parse.
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 5-parameter create operation with no annotations, no output schema, and no schema descriptions, this is not a complete definition. The description misses parameter details, input formats, result/error behavior, and any explicit differentiation from sibling tools.
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 0%, and the description does not compensate by explaining any of the parameters. The agent must rely entirely on parameter names like date, amount, category, subcategory, and note, with no type, format, or semantic guidance.
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 operation: 'Add a new expense entry to the database.' It uses a specific verb and resource, and the action is distinct from the sibling tools list_expenses and summarize, though it does not explicitly name them.
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 about when to use this tool versus list_expenses or summarize outside of the obvious 'add' intent. There are no prerequisite conditions, exclusions, or alternative routing hints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add two numbers together.
| Name | Required | Description | Default |
|---|---|---|---|
| a | Yes | ||
| b | Yes |
| 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 carries the full burden. It states the operation but does not explicitly mention that it is pure, has no side effects, or what the return value is. While obvious for addition, it falls short of full transparency.
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 a single, direct sentence with zero filler. It is front-loaded and every word earns its place, exemplifying appropriate conciseness.
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 trivial addition tool with a clear input schema and an output schema (as indicated by the signal), the description is largely sufficient. It lacks explicit mention of edge cases or preconditions, but none are expected for this operation, making it nearly complete.
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 0%—the description does not mention parameters by name or add any nuance. The schema already declares a and b as required numbers, but the description adds no value beyond that, failing to compensate for the low 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 'Add two numbers together' uses a specific verb and resource, clearly stating exactly what the tool does. It is distinct from siblings like roll_dice and add_expense, so agents can easily differentiate.
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 no guidance on when to use this tool versus alternatives, nor any exclusions. There is no context about when addition is appropriate or not, leaving the agent to infer usage from the name and schema alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List expense entries, optionally filtered within an inclusive date range.
| Name | Required | Description | Default |
|---|---|---|---|
| end_date | No | ||
| start_date | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'List' implies a read operation but does not explicitly state it is read-only or side-effect-free. It also fails to describe behavior when filters are omitted (e.g., returns all expenses) or any limits/pagination. The inclusive date range note is useful but incomplete.
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?
A single, front-loaded sentence conveys the primary purpose and optional filtering without wasted words. It is appropriately compact and easy to parse.
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 optional parameters and no output schema, the description gives the core purpose but lacks parameter format details, explicit read-only behavior, and return value expectations. It is minimally sufficient for basic use but leaves gaps that could cause incorrect calls.
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 0% – the schema provides no parameter explanations. The description only clarifies that the date range is inclusive, but does not specify date format, semantics of null defaults, or behavior when a single bound is provided. This leaves significant ambiguity for an agent.
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 states a specific verb ('List') and resource ('expense entries'), and mentions optional date filtering. This clearly distinguishes it from add_expense (creation) and the unrelated dice/number/summary tools, so an agent can easily tell what it does.
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 siblings, such as when to list vs. add expenses. The agent must infer usage from the name alone; there is no explicit context, exclusions, or alternatives mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Roll n_dice 6-sided dice and return the results.
| Name | Required | Description | Default |
|---|---|---|---|
| n_dice | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It correctly implies a random stochastic process and states the output ('return the results'), but does not explicitly mention randomness, the range of outcomes (1–6 per die), or that subsequent calls produce independent results. This is adequate for a simple tool but lacks any deeper context.
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 a single sentence, front-loaded with the core action, and contains no filler words. Every term contributes to understanding the tool's behavior.
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 low complexity (one parameter, simple output) and the presence of an output schema, the description is complete enough. It explains the parameter's role and the action's purpose. It could mention the non-deterministic nature more explicitly, but that is implicit for a dice-rolling tool, and the output schema likely covers return formatting.
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 input schema has zero description coverage for the parameter n_dice, so the description must compensate. It does so by framing n_dice as the number of dice to roll, adding semantic meaning to an otherwise bare integer field. However, it does not specify constraints like minimum value or positivity, which would have improved clarity further.
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 states a clear, specific action: 'Roll n_dice 6-sided dice and return the results.' The verb 'Roll' and resource 'dice' are unambiguous, and the tool is easily distinguished from siblings like add_numbers or list_expenses, which handle arithmetic or expense management.
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?
There is no guidance about when to use this tool versus alternatives, nor any exclusions or prerequisites. Sibling tools are unrelated, but the description provides no context for selection, leaving the agent to infer its suitability from the name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Summarize expenses by category within an inclusive date range.
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | ||
| end_date | Yes | ||
| start_date | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the behavioral burden. It discloses that the date range is inclusive, which is useful, but it does not mention whether the operation is read-only, what metrics are returned, or how categories with no expenses are handled.
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 a single front-loaded sentence with no redundancy or filler. Every word contributes to the tool's core behavior.
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 three-parameter summarization tool, the description gives the essential operation but leaves gaps. With no annotations and no output schema, it should say more about the return shape, optional category behavior, and what 'summarize' actually computes.
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 provides no descriptions for any parameter (0% coverage), so the description must compensate. It adds meaning by connecting category to grouping and start_date/end_date to an inclusive range, but it does not clarify whether category is a filter or required grouping key, nor the expected date format.
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 states a specific verb ('summarize') and resource ('expenses'), and adds the grouping dimension (by category) and date range scope. This clearly distinguishes it from the sibling tools add_expense and list_expenses.
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 intended use is implied: summarize rather than add or list expenses. However, there is no explicit guidance about when to prefer this tool over list_expenses or what scenarios it is not suited for, leaving some inference to the agent.
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.
v0.1.0add_expenseadd_numberslist_expensesroll_dicesummarizeScored across 5 tools
The three expense tools are clearly distinct, but the presence of roll_dice and add_numbers is jarring and creates confusion about the server's purpose. While they don't overlap with each other or the expense tools, their irrelevance makes the tool set feel incoherent and may cause an agent to question selection.
Naming is inconsistent: 'add_expense' and 'add_numbers' share a verb but target different domains, while 'roll_dice', 'list_expenses', and 'summarize' use different verb styles. No consistent pattern (e.g., verb_noun) is followed across all tools.
With only 5 tools, two of which are completely unrelated to expense tracking, the effective tool count for the intended domain is 3. An expense tracker typically requires more operations (e.g., update, delete, get by ID), so the surface feels thin and under-scoped.
The expense domain is missing essential CRUD operations: there is no update_expense, delete_expense, or get_expense by ID. The only available operations are create, list, and summarize, leaving significant gaps that would hinder an agent from managing expenses effectively.
Build your own tools from chat: design, test and host them on a shareable MCP server URL.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
