convez.ai
MCP ServerFinanceiroIntermediário
JiwaFinancials

Jiwa MCP Server

JiwaFinancials/JiwaMCPServer

Integre Jiwa Financials com agentes de IA via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que conecta sua instância Jiwa Financials a agentes de IA, permitindo consultas e operações no sistema financeiro. Construído em .NET 10, expõe dados de clientes, produtos e pedidos de vendas através de ferramentas padronizadas.

Instalação

$npx convez-ai JiwaFinancials/JiwaMCPServer

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
1
Saúde
25%
Último commit
há 1 semana
Versão
1.0.0.3
Issues abertas
0
Contribuidores
2

Casos de uso

  • Consultar dados de clientes e transações via agente de IA
  • Criar e modificar pedidos de vendas automaticamente
  • Buscar informações de produtos e estoque em tempo real
  • Automatizar operações financeiras com AI agents

Veredito

Solução robusta para integração de ERP financeiro com IA. Bem arquitetada, oferece autenticação granular por requisição e suporte a operações CRUD em dados críticos do negócio.

README

A tradução para o português deste README ainda está na fila.

Jiwa MCP Server

An MCP (Model Context Protocol) server that exposes Jiwa Financials business data to AI agents and MCP-compatible clients. Built with .NET 10 and ASP.NET Core, it uses the streamable HTTP transport.

Table of Contents


Prerequisites

  • .NET 10 SDK
  • Access to a running Jiwa Financials API instance
  • A valid Jiwa API key

Project Structure

JiwaMcpServer/
├── JiwaMcpServer.csproj
├── Program.cs
├── Config.cs
├── appsettings.json
├── Tools/
│   ├── JiwaToolBase.cs
│   ├── CustomerTools.cs
│   ├── ProductTools.cs
│   ├── SalesOrderTools.cs
│   └── SchemaTools.cs
└── Services/
    └── JiwaApiClient.cs

Available Tools

CustomerTools

ToolDescription
SearchCustomersSearch for customers (debtors/accounts) by field
GetCustomerGet full details for a customer
GetCustomerTransactionsRetrieve outstanding transactions (invoices/credits) for a customer

ProductTools

ToolDescription
SearchProductsSearch for products (inventory items) by field
GetProductGet full details for a product
GetStockOnHandGet stock on hand quantities for a product

SalesOrderTools

ToolDescription
SearchSalesOrdersSearch for sales orders (invoices) by field
GetSalesOrderGet full details for a sales order
CreateSalesOrderCreate a new sales order for a customer
ModifySalesOrderModify an existing sales order
AddAProductToASalesOrderAdd a product line to an existing sales order

SchemaTools

ToolDescription
GetDtoSchemaReturns the DTO schema for any Jiwa DTO type by name (useful for discovering available fields before calling other tools)

Configuration

Configuration is stored in appsettings.json in the application directory.

{
  "JiwaAPIURL": "https://your-jiwa-instance.example.com",
  "JiwaAPIKey": ""
}
SettingDescription
JiwaAPIURLThe base URL of your Jiwa Financials REST API
JiwaAPIKey(Optional) A server-side fallback Jiwa API key. When set, it is used for any request that does not supply its own key via the X-Jiwa-API-Key header. Can be left blank if all clients supply their own key.

Note: JiwaAPIURL is required. JiwaAPIKey is optional — see Per-Request API Key below.

Per-Request API Key

In addition to (or instead of) a server-side JiwaAPIKey in appsettings.json, clients can supply a Jiwa API key on a per-request basis using the X-Jiwa-API-Key HTTP header:

X-Jiwa-API-Key: <your-jiwa-api-key>

This allows each MCP client (or each user) to authenticate to Jiwa with their own API key, without sharing a single server-level credential. The priority is:

  1. X-Jiwa-API-Key header — used if present and non-empty.
  2. JiwaAPIKey in appsettings.json — used as a fallback if no header is supplied.

If neither is set, calls to the Jiwa API will be made without a bearer token and will fail unless the Jiwa endpoint allows anonymous access.

Changing the Port

By default the server listens on http://localhost:5000. To change this, set the ASPNETCORE_URLS environment variable or add a urls entry to appsettings.json:

{
  "JiwaAPIURL": "https://your-jiwa-instance.example.com",
  "JiwaAPIKey": "your-api-key-here",
  "urls": "http://0.0.0.0:8080"
}

Building and Running

Run from source

# Clone the repository
git clone https://github.com/JiwaFinancials/JiwaMcpServer.git
cd JiwaMcpServer

# Edit appsettings.json with your Jiwa API URL and key
notepad appsettings.json

# Run
dotnet run

The server will start and listen on http://localhost:5000 by default. The MCP endpoint is available at:

http://localhost:5000/mcp

Publish a self-contained executable

dotnet publish -c Release -r win-x64 --self-contained true -o ./publish

Replace win-x64 with your target runtime (e.g. linux-x64, osx-x64). Copy appsettings.json alongside the executable and edit it with your settings before running.


Using with VS Code and GitHub Copilot

This section walks through configuring VS Code and GitHub Copilot to use the Jiwa MCP Server as a tool source in Copilot Chat (Agent mode).

Prerequisites

Step 1 — Start the MCP Server

Start the server before configuring VS Code so you can verify connectivity later.

cd C:\path\to\JiwaMcpServer
dotnet run

Confirm it is listening:

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:5000

Step 2 — Register the Server in VS Code

VS Code looks for MCP server definitions in two places. Choose whichever suits your workflow:

Option A — Workspace config (per-project, do not commit if it contains tokens)

Create or edit .vscode/mcp.json in your workspace root:

{
  "servers": {
    "Jiwa": {
      "type": "http",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "X-Jiwa-API-Key": "<your-jiwa-api-key>"
      }
    }
  }
}

⚠️ This file will contain your Jiwa API key. Add it to .gitignore to avoid accidentally committing it:

.vscode/mcp.json

Option B — User config (applies to all your VS Code workspaces)

Open the VS Code command palette (Ctrl+Shift+P) and run:

MCP: Open User Configuration

This opens your global mcp.json. Add the same entry:

{
  "servers": {
    "Jiwa": {
      "type": "http",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "X-Jiwa-API-Key": "<your-jiwa-api-key>"
      }
    }
  }
}

Tip: Replace <your-jiwa-api-key> with your personal Jiwa API key.

Step 3 — Enable the Server in Copilot Chat

  1. Open the Copilot Chat panel (Ctrl+Alt+I).
  2. Switch to Agent mode by clicking the mode selector at the top of the chat input and choosing Agent.
  3. Click the Tools button (🔧) at the bottom of the chat input to open the tool picker.
  4. Locate jiwa in the list and ensure it is checked/enabled.

You should see all available Jiwa tools listed (SearchCustomers, GetProduct, CreateSalesOrder, etc.).

Step 4 — Verify the Connection

In Copilot Chat (Agent mode) type a test prompt such as:

List all available Jiwa MCP tools

or try a real query:

Search for customers with the name "Smith" using the Jiwa tools

Copilot will call the appropriate tool and return results from your Jiwa system.

Step 5 — (Optional) Auto-start the Server

To avoid manually starting the server each time, you can configure a VS Code task that launches it automatically.

Create or edit .vscode/tasks.json:

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Start Jiwa MCP Server",
      "type": "shell",
      "command": "dotnet run --project ${workspaceFolder}/JiwaMcpServer.csproj",
      "isBackground": true,
      "problemMatcher": {
        "pattern": {
          "regexp": "^$"
        },
        "background": {
          "activeOnStart": true,
          "beginsPattern": "Building\\.\\.\\.",
          "endsPattern": "Now listening on:"
        }
      },
      "presentation": {
        "reveal": "silent",
        "panel": "dedicated"
      }
    }
  ]
}

Then reference it as a pre-launch dependency in .vscode/launch.json or trigger it manually via Terminal → Run Task → Start Jiwa MCP Server.

Troubleshooting

ProblemSolution
Tools not appearing in Copilot ChatEnsure the server is running and accessible at the configured URL. Open a browser to http://localhost:5000/mcp — you should receive an MCP response, not a connection error.
ERR_CONNECTION_REFUSEDThe server is not running or is listening on a different port. Check the console output and verify appsettings.json.
Jiwa API returns 401 / Unauthorized
Copilot asks for confirmation before every tool callThis is expected behaviour in Agent mode. You can approve individual calls or select Always Allow for trusted tools.
Server returns 500 errorsCheck that JiwaAPIURL in appsettings.json is correct, that a Jiwa API key is being supplied (see above), and that your Jiwa instance is reachable from the machine running the MCP server.

Connecting an MCP Client

The server uses the streamable HTTP transport. The MCP endpoint is:

http://<host>:<port>/mcp

Requests may optionally include the X-Jiwa-API-Key header with a Jiwa API key:

X-Jiwa-API-Key: <your-jiwa-api-key>

The X-Jiwa-API-Key header is required if no server-side fallback key is configured in appsettings.json. See Per-Request API Key for details.

GitHub Copilot (VS Code)

See the dedicated Using with VS Code and GitHub Copilot section above for full step-by-step instructions.

For a quick reference, add the following to .vscode/mcp.json in your workspace (or your user-level mcp.json):

{
  "servers": {
    "Jiwa": {
      "type": "http",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "X-Jiwa-API-Key": "<your-jiwa-api-key>"
      }
    }
  }
}

GitHub Copilot (Visual Studio)

Add the following to your mcp.json (typically at %USERPROFILE%\.vs\mcp.json or the solution's .vs\mcp.json):

{
  "servers": {
    "Jiwa": {
      "type": "http",
      "url": "http://localhost:5000/mcp",
      "headers": {
        "X-Jiwa-API-Key": "<your-jiwa-api-key>"
      }
    }
  }
}

MCP Inspector (for testing)

You can test the server with the MCP Inspector:

npx -y @modelcontextprotocol/inspector http://localhost:5000/mcp

Deploying to a Server

Windows (as a Windows Service)

  1. Publish the application:

    dotnet publish -c Release -r win-x64 --self-contained true -o C:\Services\JiwaMcpServer
    
  2. Copy and edit appsettings.json in the publish folder with your settings.

  3. Register as a Windows Service:

    sc.exe create JiwaMcpServer binPath="C:\Services\JiwaMcpServer\JiwaMcpServer.exe" start=auto
    sc.exe start JiwaMcpServer
    

Linux (as a systemd service)

  1. Publish the application:

    dotnet publish -c Release -r linux-x64 --self-contained true -o /opt/jiwamcpserver
    
  2. Edit /opt/jiwamcpserver/appsettings.json with your settings.

  3. Create a systemd unit file at /etc/systemd/system/jiwamcpserver.service:

    [Unit]
    Description=Jiwa MCP Server
    After=network.target
    
    [Service]
    WorkingDirectory=/opt/jiwamcpserver
    ExecStart=/opt/jiwamcpserver/JiwaMcpServer
    Restart=always
    RestartSec=10
    Environment=ASPNETCORE_ENVIRONMENT=Production
    Environment=ASPNETCORE_URLS=http://0.0.0.0:5000
    
    [Install]
    WantedBy=multi-user.target
    
  4. Enable and start the service:

    sudo systemctl daemon-reload
    sudo systemctl enable jiwamcpserver
    sudo systemctl start jiwamcpserver
    

Behind a Reverse Proxy (nginx / IIS)

When hosting behind a reverse proxy, configure it to forward requests to the MCP endpoint. Example nginx snippet:

location /mcp {
    proxy_pass         http://localhost:5000/mcp;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection keep-alive;
    proxy_set_header   Host $host;
    proxy_cache_bypass $http_upgrade;
    proxy_buffering    off;
}

Tip: Disable proxy response buffering (proxy_buffering off) to ensure streaming responses are forwarded immediately to the client.

Ver o original no GitHub

Bom para

Relacionados