{"_id":"@adflz/sure-mcp","_rev":"3-c341c2847b276793cc9c3fb9fb3365b1","name":"@adflz/sure-mcp","dist-tags":{"latest":"0.3.0"},"versions":{"0.1.0":{"name":"@adflz/sure-mcp","version":"0.1.0","keywords":["mcp","model-context-protocol","sure","finance","llm","ai-agents"],"author":{"name":"Adão Viana Pinto","email":"adaofeliz@users.noreply.github.com"},"license":"MIT","_id":"@adflz/sure-mcp@0.1.0","maintainers":[{"name":"adflz","email":"adaofeliz@gmail.com"}],"homepage":"https://github.com/adaofeliz/sure-mcp#readme","bugs":{"url":"https://github.com/adaofeliz/sure-mcp/issues"},"bin":{"sure-mcp":"dist/index.js"},"dist":{"shasum":"2b876532c77f08036f10207c9781f922f2ee3b65","tarball":"https://registry.npmjs.org/@adflz/sure-mcp/-/sure-mcp-0.1.0.tgz","fileCount":5,"integrity":"sha512-NLilFpwAUJr/J1zNVdbHYEfVDksNphGlZz5xqcexKJq1ohYX5FfIJSrHu/5fM3nFGnxlyNWqIM4RUw/31DFjxw==","signatures":[{"sig":"MEYCIQD5MDLX25hpeoRXXFl0A0g1awQGpsj3sqPO8tRL0jJ1oQIhAPSH1+hqfm7c8w19Web1B5SsB3YbkAbVIUIR3THCdBSg","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":34390},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=20"},"gitHead":"80ca9b03ef2b662e7ffcb1d25f5f8fe86762dbb3","scripts":{"dev":"tsup --watch","build":"tsup","clean":"rm -rf dist","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"bun run clean && bun run build"},"_npmUser":{"name":"adflz","email":"adaofeliz@gmail.com"},"repository":{"url":"git+https://github.com/adaofeliz/sure-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"MCP server for the Sure finance API — CRUD for transactions & tags, read for categories, merchants, accounts.","directories":{},"_nodeVersion":"20.20.2","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.3.0","typescript":"^5.5.0","@types/node":"^20.14.0"},"_npmOperationalInternal":{"tmp":"tmp/sure-mcp_0.1.0_1777508739850_0.8438243457663228","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@adflz/sure-mcp","version":"0.2.0","keywords":["mcp","model-context-protocol","sure","finance","llm","ai-agents"],"author":{"name":"Adão Viana Pinto","email":"adaofeliz@users.noreply.github.com"},"license":"MIT","_id":"@adflz/sure-mcp@0.2.0","maintainers":[{"name":"adflz","email":"adaofeliz@gmail.com"}],"homepage":"https://github.com/adaofeliz/sure-mcp#readme","bugs":{"url":"https://github.com/adaofeliz/sure-mcp/issues"},"bin":{"sure-mcp":"dist/index.js"},"dist":{"shasum":"8948417b5c405e069679855554e9852d90a470ab","tarball":"https://registry.npmjs.org/@adflz/sure-mcp/-/sure-mcp-0.2.0.tgz","fileCount":38,"integrity":"sha512-AlLRUbrfJ/pviUxQdFZ1qcDbNpXA1Hzvx7+Em7JWZ7D+izTC8z6skcxQtaEiYQQ1GQ0YyUBpW5ariTF+/4lb8g==","signatures":[{"sig":"MEYCIQDD6fkOkj525oNjU8cCbY6/4KOiUS6AUiLkOuEIU+8WKAIhAM/q/Az6xL6MP4iGq23tFef6l1zx4JGPhYmilF9N4GU3","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":133563},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=22"},"gitHead":"b93b0b277ac9de4c7369b728da3a28dfd146bb13","scripts":{"dev":"tsup --watch","build":"tsup","clean":"rm -rf dist","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"bun run clean && bun run build"},"_npmUser":{"name":"adflz","email":"adaofeliz@gmail.com"},"repository":{"url":"git+https://github.com/adaofeliz/sure-mcp.git","type":"git"},"_npmVersion":"10.9.7","description":"MCP server for the Sure finance API — CRUD for transactions & tags, read for categories, merchants, accounts.","directories":{},"_nodeVersion":"22.22.2","dependencies":{"zod":"^3.25.0","@modelcontextprotocol/sdk":"^1.29.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.1","typescript":"^6.0.3","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/sure-mcp_0.2.0_1777552841087_0.9141842240742182","host":"s3://npm-registry-packages-npm-production"}},"0.3.0":{"name":"@adflz/sure-mcp","version":"0.3.0","description":"MCP server for the Sure finance API — CRUD for transactions & tags, read for budgets, categories, merchants, and accounts.","type":"module","license":"MIT","author":{"name":"Adão Viana Pinto","email":"adaofeliz@users.noreply.github.com"},"repository":{"type":"git","url":"git+https://github.com/adaofeliz/sure-mcp.git"},"homepage":"https://github.com/adaofeliz/sure-mcp#readme","bugs":{"url":"https://github.com/adaofeliz/sure-mcp/issues"},"keywords":["mcp","model-context-protocol","sure","finance","llm","ai-agents"],"bin":{"sure-mcp":"dist/index.js"},"main":"./dist/index.js","types":"./dist/index.d.ts","engines":{"node":">=22"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","start":"node dist/index.js","clean":"rm -rf dist","prepublishOnly":"bun run clean && bun run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","zod":"^3.25.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.5.1","typescript":"^6.0.3"},"_id":"@adflz/sure-mcp@0.3.0","gitHead":"77d522005b391ad93eff8aac13a1c7e36c462a21","_nodeVersion":"22.22.3","_npmVersion":"10.9.8","dist":{"integrity":"sha512-k6bBLr7xIcUxmgJLDbiH9aY2RTnZlVZ153OVfKsdpWT8nnW1hNluSd9juz4c1KJE6+VDnXAHYTtrVxyI4uVXkQ==","shasum":"731fc8bb2c34324ab79a2a7dd6ffac280e0f2c10","tarball":"https://registry.npmjs.org/@adflz/sure-mcp/-/sure-mcp-0.3.0.tgz","fileCount":45,"unpackedSize":175106,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCICrYxSVrm9WK35LxGkKu8dT/EJQIKQi/IvA6y7TnYkk8AiAHOwMJ21beufNqnrPe+FAhRnGXtxgpOSos4qdrFO1bAQ=="}]},"_npmUser":{"name":"adflz","email":"adaofeliz@gmail.com"},"directories":{},"maintainers":[{"name":"adflz","email":"adaofeliz@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sure-mcp_0.3.0_1780592385844_0.5968123502414844"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T00:25:39.778Z","modified":"2026-06-04T16:59:46.135Z","0.1.0":"2026-04-30T00:25:40.021Z","0.2.0":"2026-04-30T12:40:41.250Z","0.3.0":"2026-06-04T16:59:46.004Z"},"bugs":{"url":"https://github.com/adaofeliz/sure-mcp/issues"},"author":{"name":"Adão Viana Pinto","email":"adaofeliz@users.noreply.github.com"},"license":"MIT","homepage":"https://github.com/adaofeliz/sure-mcp#readme","keywords":["mcp","model-context-protocol","sure","finance","llm","ai-agents"],"repository":{"type":"git","url":"git+https://github.com/adaofeliz/sure-mcp.git"},"description":"MCP server for the Sure finance API — CRUD for transactions & tags, read for budgets, categories, merchants, and accounts.","maintainers":[{"name":"adflz","email":"adaofeliz@gmail.com"}],"readme":"# sure-mcp\n\n[![npm](https://img.shields.io/npm/v/@adflz/sure-mcp)](https://www.npmjs.com/package/@adflz/sure-mcp) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Node >=22](https://img.shields.io/badge/node-%3E%3D22-brightgreen)](https://nodejs.org)\n\nA Model Context Protocol (MCP) server for the [Sure](https://github.com/we-promise/sure) finance API. Exposes 21 typed tools for AI agents to read accounts, categories, and merchants; and full CRUD for transactions and tags. Designed for transaction-enrichment automation: let an agent look up merchant details on the web, assign categories, manage tags, and update transactions autonomously.\n\n---\n\n## Requirements\n\n- Node.js 22 or higher\n- A running [Sure](https://github.com/we-promise/sure) instance (self-hosted or cloud)\n- An API key generated from your Sure account settings\n\n---\n\n## Installation\n\n### Claude Desktop\n\nAdd the server to your Claude Desktop configuration file:\n\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"sure\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@adflz/sure-mcp\"],\n      \"env\": {\n        \"SURE_URL\": \"https://sure.example.com\",\n        \"SURE_API_KEY\": \"<your-sure-api-key>\"\n      }\n    }\n  }\n}\n```\n\n### Claude Code\n\nAdd the server to your MCP configuration:\n\n- Project-level: `.claude/mcp.json`\n- Global: `~/.claude/mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"sure\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@adflz/sure-mcp\"],\n      \"env\": {\n        \"SURE_URL\": \"https://sure.example.com\",\n        \"SURE_API_KEY\": \"<your-sure-api-key>\"\n      }\n    }\n  }\n}\n```\n\n> **Note**: Any stdio-compatible MCP client can use this server. Use [MCP Inspector](https://github.com/modelcontextprotocol/inspector) to debug MCP communication.\n\n---\n\n## Configuration\n\n| Variable | Description | Required |\n|----------|-------------|----------|\n| `SURE_URL` | Base URL of your Sure instance (e.g., `https://sure.example.com`). Do not include `/api/v1` or trailing slashes. | Yes |\n| `SURE_API_KEY` | API key generated from Sure account settings → API keys. Keep this secret; never commit it to source control. | Yes |\n\n---\n\n## Tools\n\nThe server exposes 21 typed tools across 7 resource types. All tools use the MCP request/response format.\n\n| Tool | Resource | Operation | Annotations |\n|------|----------|-----------|-------------|\n| `list_transactions` | Transactions | List with filters | read-only |\n| `get_transaction` | Transactions | Get by ID | read-only |\n| `create_transaction` | Transactions | Create | — |\n| `update_transaction` | Transactions | Update fields | idempotent |\n| `delete_transaction` | Transactions | Delete | destructive, idempotent |\n| `list_tags` | Tags | List all | read-only |\n| `get_tag` | Tags | Get by ID | read-only |\n| `create_tag` | Tags | Create | — |\n| `update_tag` | Tags | Update name/color | idempotent |\n| `delete_tag` | Tags | Delete | destructive, idempotent |\n| `list_categories` | Categories | List with filters | read-only |\n| `get_category` | Categories | Get by ID | read-only |\n| `list_merchants` | Merchants | List all | read-only |\n| `get_merchant` | Merchants | Get by ID | read-only |\n| `list_accounts` | Accounts | List all | read-only |\n| `get_account` | Accounts | Get by ID | read-only |\n| `list_budgets` | Budgets | List with pagination | read-only |\n| `get_budget` | Budgets | Get by ID (full metrics) | read-only |\n| `get_current_budget` | Budgets | Get active budget | read-only |\n| `list_budget_categories` | Budget Categories | List with filters | read-only |\n| `get_budget_category` | Budget Categories | Get by ID (full metrics) | read-only |\n\n---\n\n## Example workflows\n\n### Enrich transactions\n\n1. Call `list_transactions` with filters for recent uncategorized entries (e.g., `start_date` set to 30 days ago, `per_page=50`).\n2. For each transaction, research the merchant name using external tools.\n3. Call `update_transaction` with the resolved `category_id`, `merchant_id`, and `tag_ids`.\n4. Repeat until all uncategorized transactions are enriched.\n\n### Bulk re-tag\n\n1. Call `list_transactions` filtered by a specific merchant ID.\n2. For each transaction, call `update_transaction` to apply a new tag via `tag_ids`.\n3. Optionally remove old tags by excluding them from subsequent updates.\n\n### Monthly review\n\n1. Call `list_transactions` with `start_date` and `end_date` for the previous month, `per_page=100`.\n2. Aggregate results by category to produce spending summaries.\n3. Export or store the summary for reporting.\n\n---\n\n## Limitations\n\n- **Categories and merchants are read-only** via the Sure API. Create or edit them in the Sure web UI.\n- **No automatic retry** is implemented. The server surfaces 429 (rate limit) and 5xx errors directly; the consuming agent decides how to proceed.\n- **Transport**: stdio only. HTTP and SSE transports are not supported.\n\n---\n\n## Local development\n\n```bash\n# Clone the repository\ngit clone https://github.com/adaofeliz/sure-mcp.git\ncd sure-mcp\n\n# Install dependencies\nbun install\n\n# Typecheck\nbun run typecheck\n\n# Build\nbun run build\n\n# Smoke test (requires SURE_URL and SURE_API_KEY in environment)\nnpx -y @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list\n```\n\n### Releasing\n\n1. Update the version in `package.json`\n2. Commit changes: `git commit -m \"Release vX.Y.Z\"`\n3. Create and push a tag: `git tag vX.Y.Z && git push origin vX.Y.Z`\n4. GitHub Actions publishes to npm automatically. Ensure `NPM_TOKEN` is set in repository secrets.\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## Security\n\nSee [SECURITY.md](SECURITY.md).\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n","readmeFilename":"README.md"}