siigo-mcp-server 1.0.0

package/.env.example

@@ -0,0 +1,10 @@
+# Siigo API Configuration
+SIIGO_USERNAME=your_siigo_username
+SIIGO_ACCESS_KEY=your_siigo_access_key
+SIIGO_BASE_URL=https://api.siigo.com
+SIIGO_PARTNER_ID=siigo-mcp-server
+
+# Optional: Use sandbox environment for testing
+# SIIGO_BASE_URL=https://api.siigo.com
+# SIIGO_USERNAME=sandbox@siigoapi.com
+# SIIGO_ACCESS_KEY=your_sandbox_access_key

package/README.md

@@ -0,0 +1,245 @@
+# Siigo MCP Server
+
+A Model Context Protocol (MCP) server that provides integration with the Siigo API, enabling access to Colombian accounting software features including products, customers, invoices, purchases, credit notes, vouchers, payment receipts, and journals.
+
+## Features
+
+This MCP server provides access to all major Siigo API endpoints:
+
+### Core Resources
+- **Products**: Create, read, update, and delete products/services
+- **Customers**: Manage customer/supplier information
+- **Invoices**: Handle sales invoices with electronic invoicing support
+- **Purchases**: Manage purchase invoices and expenses
+- **Credit Notes**: Create and manage credit notes
+- **Vouchers**: Handle cash receipts (recibos de caja)
+- **Payment Receipts**: Manage payment receipts/disbursements
+- **Journals**: Handle accounting journal entries
+
+### Catalogs
+- Document types, taxes, payment types
+- Cost centers, users, warehouses
+- Price lists, account groups, cities
+- ID types, fiscal responsibilities
+
+### Reports
+- Trial balance reports
+- Trial balance by third party
+- Accounts payable reports
+
+## Installation
+
+1. Clone this repository:
+```bash
+git clone <repository-url>
+cd siigo-mcp
+```
+
+2. Install dependencies:
+```bash
+npm install
+```
+
+3. Build the TypeScript code:
+```bash
+npm run build
+```
+
+4. Set up environment variables by copying the example file:
+```bash
+cp .env.example .env
+```
+
+5. Edit `.env` with your Siigo credentials:
+```bash
+SIIGO_USERNAME=your_siigo_username
+SIIGO_ACCESS_KEY=your_siigo_access_key
+SIIGO_BASE_URL=https://api.siigo.com
+SIIGO_PARTNER_ID=your_app_name
+```
+
+## Configuration
+
+### Required Environment Variables
+
+- `SIIGO_USERNAME`: Your Siigo API username
+- `SIIGO_ACCESS_KEY`: Your Siigo API access key
+
+### Optional Environment Variables
+
+- `SIIGO_BASE_URL`: API base URL (defaults to `https://api.siigo.com`)
+- `SIIGO_PARTNER_ID`: Partner ID for API identification (defaults to `siigo-mcp-server`)
+
+### Getting Siigo API Credentials
+
+1. Sign up for a Siigo account at [siigo.com](https://siigo.com)
+2. Access the API section in your Siigo dashboard
+3. Generate your API credentials (username and access key)
+4. For testing, you can use the sandbox environment
+
+## Usage
+
+### Running the Server
+
+Start the MCP server:
+```bash
+npm start
+```
+
+For development with auto-reload:
+```bash
+npm run dev
+```
+
+### Available Tools
+
+The server provides 40+ tools for interacting with the Siigo API. Here are some examples:
+
+#### Products
+- `siigo_get_products` - List all products
+- `siigo_get_product` - Get a specific product by ID
+- `siigo_create_product` - Create a new product
+- `siigo_update_product` - Update an existing product
+- `siigo_delete_product` - Delete a product
+
+#### Customers
+- `siigo_get_customers` - List all customers
+- `siigo_get_customer` - Get a specific customer by ID
+- `siigo_create_customer` - Create a new customer
+- `siigo_update_customer` - Update an existing customer
+
+#### Invoices
+- `siigo_get_invoices` - List all invoices
+- `siigo_get_invoice` - Get a specific invoice by ID
+- `siigo_create_invoice` - Create a new invoice
+- `siigo_update_invoice` - Update an existing invoice
+- `siigo_delete_invoice` - Delete an invoice
+- `siigo_get_invoice_pdf` - Get invoice PDF
+- `siigo_send_invoice_email` - Send invoice by email
+
+#### Catalogs
+- `siigo_get_document_types` - Get document types
+- `siigo_get_taxes` - Get tax information
+- `siigo_get_payment_types` - Get payment methods
+- `siigo_get_cost_centers` - Get cost centers
+- `siigo_get_users` - Get system users
+
+#### Reports
+- `siigo_get_trial_balance` - Generate trial balance report
+- `siigo_get_accounts_payable` - Get accounts payable report
+
+### Example Usage
+
+#### Creating a Product
+```json
+{
+  "name": "siigo_create_product",
+  "arguments": {
+    "product": {
+      "code": "PROD001",
+      "name": "Test Product",
+      "account_group": 1253,
+      "type": "Product",
+      "active": true,
+      "description": "A test product"
+    }
+  }
+}
+```
+
+#### Creating a Customer
+```json
+{
+  "name": "siigo_create_customer",
+  "arguments": {
+    "customer": {
+      "person_type": "Person",
+      "id_type": "13",
+      "identification": "12345678",
+      "name": ["John", "Doe"],
+      "address": {
+        "address": "123 Main St",
+        "city": {
+          "country_code": "Co",
+          "state_code": "11",
+          "city_code": "11001"
+        }
+      },
+      "phones": [{"number": "1234567890"}],
+      "contacts": [{
+        "first_name": "John",
+        "last_name": "Doe",
+        "email": "john@example.com"
+      }]
+    }
+  }
+}
+```
+
+## API Rate Limits
+
+Siigo API has the following rate limits:
+- Production: 100 requests per minute per company
+- Sandbox: 10 requests per minute
+
+## Error Handling
+
+The server handles various Siigo API errors and returns structured error responses. Common error scenarios include:
+
+- Authentication failures
+- Invalid parameters
+- Rate limit exceeded
+- Resource not found
+- Validation errors
+
+## Development
+
+### Project Structure
+
+```
+siigo-mcp/
+├── src/
+│   ├── index.ts          # Main MCP server implementation
+│   ├── siigo-client.ts   # Siigo API client
+│   └── types.ts          # TypeScript type definitions
+├── package.json
+├── tsconfig.json
+├── .env.example
+└── README.md
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+npm test
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+MIT License
+
+## Support
+
+For issues related to:
+- Siigo API: Contact Siigo support at soporteapi@siigo.com
+- This MCP server: Create an issue in this repository
+
+## Links
+
+- [Siigo API Documentation](https://siigoapi.docs.apiary.io/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+- [Siigo Official Website](https://siigo.com/)

package/bin/siigo-mcp

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const { spawn } = require('child_process');
+
+const serverPath = path.join(__dirname, '..', 'dist', 'index.js');
+
+const child = spawn('node', [serverPath], {
+  stdio: 'inherit',
+  env: process.env
+});
+
+child.on('error', (error) => {
+  console.error('Failed to start Siigo MCP server:', error);
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code);
+});

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}