financeops-mcp 0.1.0

package/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,29 @@
+---
+name: Bug Report
+about: Report a bug in FinanceOps MCP
+labels: bug
+---
+
+**Provider:** Stripe / Xero / Both
+
+**Tool:** (e.g., financial_health, generate_pnl, reconcile)
+
+**Steps to Reproduce:**
+1.
+2.
+3.
+
+**Expected Behavior:**
+
+**Actual Behavior:**
+
+**Error Output:**
+```
+
+```
+
+**Environment:**
+- Node.js version:
+- FinanceOps version:
+- OS:
+- Pro license: Yes / No

package/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,24 @@
+---
+name: Feature Request
+about: Suggest a new feature for FinanceOps MCP
+labels: enhancement
+---
+
+**Is this related to a problem?**
+
+**Describe the feature:**
+
+**Which providers should it support?**
+- [ ] Stripe
+- [ ] Xero
+- [ ] Both
+- [ ] New provider (specify):
+
+**Type of contribution:**
+- [ ] New analysis module (P&L, forecasting, etc.)
+- [ ] New provider adapter
+- [ ] New free tool
+- [ ] New pro tool
+- [ ] Other
+
+**Use case:**

package/.github/assets/banner.svg

@@ -0,0 +1,104 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 800 200" width="800" height="200">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0d1117;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#0a1f16;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="accent" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#10b981;stop-opacity:1" />
+      <stop offset="100%" style="stop-color:#34d399;stop-opacity:1" />
+    </linearGradient>
+    <linearGradient id="glow" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" style="stop-color:#10b981;stop-opacity:0.25" />
+      <stop offset="100%" style="stop-color:#10b981;stop-opacity:0" />
+    </linearGradient>
+    <filter id="shadow">
+      <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#10b981" flood-opacity="0.3"/>
+    </filter>
+    <filter id="textGlow">
+      <feGaussianBlur in="SourceGraphic" stdDeviation="2" result="blur"/>
+      <feMerge>
+        <feMergeNode in="blur"/>
+        <feMergeNode in="SourceGraphic"/>
+      </feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="800" height="200" fill="url(#bg)" rx="12" ry="12"/>
+
+  <!-- Subtle grid pattern -->
+  <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+    <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1a2e22" stroke-width="0.5"/>
+  </pattern>
+  <rect width="800" height="200" fill="url(#grid)" rx="12" ry="12" opacity="0.6"/>
+
+  <!-- Top accent line -->
+  <rect x="0" y="0" width="800" height="3" fill="url(#accent)" rx="1"/>
+
+  <!-- Glow halo behind icons -->
+  <ellipse cx="400" cy="145" rx="260" ry="55" fill="url(#glow)" opacity="0.5"/>
+
+  <!-- Stripe-style icon (left): vertical bars representing payments -->
+  <g transform="translate(220, 108)" filter="url(#shadow)">
+    <rect x="0" y="12" width="8" height="28" rx="2" fill="#10b981" opacity="0.85"/>
+    <rect x="12" y="6" width="8" height="34" rx="2" fill="#10b981" opacity="0.65"/>
+    <rect x="24" y="0" width="8" height="40" rx="2" fill="#10b981" opacity="0.45"/>
+    <text x="16" y="52" text-anchor="middle" font-family="'SF Mono','Fira Code','Cascadia Code',monospace" font-size="9" fill="#6b7280">Stripe</text>
+  </g>
+
+  <!-- Chart/graph icon (center): line chart representing finance analysis -->
+  <g transform="translate(374, 108)" filter="url(#shadow)">
+    <polyline points="0,36 10,22 20,28 30,10 40,18" fill="none" stroke="#10b981" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" opacity="0.9"/>
+    <circle cx="0" cy="36" r="2.5" fill="#10b981" opacity="0.9"/>
+    <circle cx="10" cy="22" r="2.5" fill="#10b981" opacity="0.9"/>
+    <circle cx="20" cy="28" r="2.5" fill="#10b981" opacity="0.9"/>
+    <circle cx="30" cy="10" r="2.5" fill="#10b981" opacity="0.9"/>
+    <circle cx="40" cy="18" r="2.5" fill="#10b981" opacity="0.9"/>
+    <line x1="0" y1="40" x2="40" y2="40" stroke="#1a2e22" stroke-width="1.5" opacity="0.8"/>
+    <text x="20" y="52" text-anchor="middle" font-family="'SF Mono','Fira Code','Cascadia Code',monospace" font-size="9" fill="#6b7280">Analysis</text>
+  </g>
+
+  <!-- Xero-style icon (right): circular X mark representing accounting -->
+  <g transform="translate(536, 108)" filter="url(#shadow)">
+    <circle cx="20" cy="18" r="20" fill="none" stroke="#10b981" stroke-width="1.5" opacity="0.7"/>
+    <line x1="12" y1="10" x2="28" y2="26" stroke="#10b981" stroke-width="2.5" stroke-linecap="round" opacity="0.85"/>
+    <line x1="28" y1="10" x2="12" y2="26" stroke="#10b981" stroke-width="2.5" stroke-linecap="round" opacity="0.85"/>
+    <text x="20" y="52" text-anchor="middle" font-family="'SF Mono','Fira Code','Cascadia Code',monospace" font-size="9" fill="#6b7280">Xero</text>
+  </g>
+
+  <!-- Connection lines from subtitle to icons -->
+  <line x1="330" y1="95" x2="244" y2="110" stroke="#10b981" stroke-width="1" opacity="0.25"/>
+  <line x1="400" y1="95" x2="394" y2="110" stroke="#10b981" stroke-width="1" opacity="0.25"/>
+  <line x1="470" y1="95" x2="556" y2="110" stroke="#10b981" stroke-width="1" opacity="0.25"/>
+
+  <!-- Currency symbol accent (top-left) -->
+  <g transform="translate(145, 38)">
+    <text x="0" y="22" font-family="'SF Mono','Fira Code','Cascadia Code',monospace" font-size="28" font-weight="bold" fill="url(#accent)" opacity="0.8">$</text>
+  </g>
+
+  <!-- Main title -->
+  <text x="400" y="55" text-anchor="middle" font-family="'SF Mono','Fira Code','Cascadia Code','Consolas',monospace" font-size="38" font-weight="bold" fill="#f0f6fc" filter="url(#textGlow)" letter-spacing="1">
+    FinanceOps MCP
+  </text>
+
+  <!-- Subtitle -->
+  <text x="400" y="82" text-anchor="middle" font-family="'SF Mono','Fira Code','Cascadia Code','Consolas',monospace" font-size="13" fill="#6b7280" letter-spacing="3">
+    UNIFIED FINANCIAL INTELLIGENCE SERVER
+  </text>
+
+  <!-- Bottom accent line -->
+  <rect x="290" y="92" width="220" height="1" fill="url(#accent)" opacity="0.35"/>
+
+  <!-- Version badge -->
+  <g transform="translate(680, 15)">
+    <rect width="60" height="20" rx="10" fill="#0a1f16" stroke="#1a3a28" stroke-width="1"/>
+    <text x="30" y="14" text-anchor="middle" font-family="'SF Mono','Fira Code',monospace" font-size="10" fill="#10b981">v0.1.0</text>
+  </g>
+
+  <!-- MCP badge -->
+  <g transform="translate(60, 15)">
+    <rect width="44" height="20" rx="10" fill="#0a1f16" stroke="#1a3a28" stroke-width="1"/>
+    <text x="22" y="14" text-anchor="middle" font-family="'SF Mono','Fira Code',monospace" font-size="10" fill="#10b981">MCP</text>
+  </g>
+</svg>

package/.github/pull_request_template.md

@@ -0,0 +1,25 @@
+## Summary
+
+Brief description of changes.
+
+## Type
+- [ ] Bug fix
+- [ ] New free tool
+- [ ] New pro tool
+- [ ] New provider adapter
+- [ ] New analysis module
+- [ ] Documentation
+
+## Provider Impact
+- [ ] Stripe
+- [ ] Xero
+- [ ] Both
+- [ ] No provider changes
+
+## Checklist
+- [ ] Tests pass (`npm test`)
+- [ ] TypeScript compiles (`npm run build`)
+- [ ] New tests added for new features
+- [ ] No real credentials in test fixtures
+- [ ] Audit log call added for new tools (`logAudit(...)`)
+- [ ] README updated if new tools or providers added

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,40 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery and unwelcome sexual attention
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project team. All complaints will be reviewed and investigated
+and will result in a response that is deemed necessary and appropriate to the
+circumstances.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

package/CONTRIBUTING.md

@@ -0,0 +1,71 @@
+# Contributing to FinanceOps MCP
+
+Thanks for your interest in contributing! FinanceOps MCP is an open-source financial intelligence server for AI coding agents. It connects Stripe and Xero to provide P&L, cash flow forecasting, reconciliation, and anomaly detection through the MCP protocol.
+
+## Getting Started
+
+1. Fork the repository
+2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/financeops-mcp.git`
+3. Install dependencies: `npm install`
+4. Run tests: `npm test`
+
+## Development
+
+- **Language:** TypeScript (strict mode)
+- **Testing:** Vitest — run `npm test`
+- **Build:** `npm run build` (TypeScript → dist/)
+- **Entry point:** `src/index.ts`
+
+## Adding a New Provider
+
+FinanceOps supports pluggable financial providers. To add a new one (e.g. QuickBooks, Braintree):
+
+1. Create `src/adapters/your-provider.ts` implementing the `FinancialProvider` interface defined in `src/adapters/types.ts`
+2. Implement the required methods:
+   - `getTransactions(options)` — paginated transaction list
+   - `getBalances()` — current account balances
+   - `getInvoices(options)` — invoice list with status filtering
+3. Register the provider in `src/lib/providers.ts`
+4. Add the provider to the `z.enum(['stripe', 'xero', 'your-provider'])` schemas in `src/index.ts`
+5. Add integration tests in `tests/adapters/your-provider.test.ts`
+6. Document credentials in README under "Supported Providers"
+
+## Adding a New Analysis Module
+
+Analysis modules live in `src/analysis/`. Each module is a pure function that takes `Transaction[]` and returns a typed result.
+
+1. Create `src/analysis/your-module.ts`
+2. Export a named function: `export function yourAnalysis(transactions: Transaction[], options: YourOptions): YourResult`
+3. Add the result type to `src/types.ts`
+4. If the analysis is a free tool, register it in the free tools list in `src/index.ts`
+5. If it is a pro tool, add it behind `requirePro()` and to the pro tools list in `src/index.ts`
+6. Add tests in `tests/analysis/your-module.test.ts`
+
+## Adding a New Tool
+
+1. Register the Zod input schema in `src/index.ts`
+2. Add the tool definition to the `ListToolsRequestSchema` handler
+3. Add the `case 'your_tool':` block in the `CallToolRequestSchema` handler
+4. Free tools go directly in the tools array; pro tools go behind `isPro()` / `requirePro()`
+5. Log every tool call with `logAudit({ tool: name, provider, success })`
+
+## Pull Requests
+
+- Write tests for new features — coverage for analysis modules is especially important
+- Ensure all tests pass: `npm test`
+- TypeScript must compile without errors: `npm run build`
+- One feature per PR — keep PRs focused and reviewable
+- Do not include real API credentials, even in tests; use mock data
+
+## Reporting Issues
+
+Use GitHub Issues. Include:
+- Steps to reproduce
+- Expected vs actual behavior
+- Provider (Stripe / Xero)
+- Node.js version
+- Any relevant error output
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the MIT License.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Craftpipe (Heijnes Digital)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.