Content
# AshybulakStroy MCP 1C Bridge
AshybulakStroy MCP 1C Bridge — MCP server for secure AI access to 1C:Accounting for Kazakhstan 3.0 data via OData.
Product role:
- This is an MCP backend for 1C Kazakhstan;
- This is a read-only Secure Mode bridge, not an LLM client;
- `AshybulakStroy_chat_LLM_Proxy` should be an upstream component that calls the MCP server separately and passes correlation metadata.
Current project focus:
- Read-only access to published OData entities of 1C;
- Search and explanation of inventory sources;
- Obtaining inventory and low inventory levels;
- Management cash reports by payments, top clients, and debtors;
- Reconciliation of MCP data with 1C report inserted as plain text;
- Guardrail pipeline for normalization and validation of documents without actual recording in 1C.
## Demo Quickstart
For quick demo and Secure Mode verification:
- [Read-only Demo Guide](docs/DEMO_READONLY_SECURE_MODE.md)
- [Demo Prompts](docs/DEMO_PROMPTS.md)
- [Demo Checklist](docs/DEMO_CHECKLIST.md)
- [Security Baseline](docs/SECURITY_BASELINE.md)
- [Audit Log Examples](docs/AUDIT_LOG_EXAMPLES.md)
## Secure Mode
The server operates in `Secure Mode`:
- Each MCP tool undergoes policy decision before execution;
- Each MCP tool registers through a secure registration helper;
- At startup, the server checks policy coverage for all registered MCP tools;
- Unknown tools are forbidden;
- Forbidden tools are blocked;
- `L3` and `L4` operations are always blocked;
- Each call is recorded in an append-only audit log;
- The result passes through an output filter before being returned to the client.
Main principle:
```text
AI can read and explain 1C data but should not have the ability to issue dangerous permissions or bypass policy.
```
## LLM Proxy Position
`AshybulakStroy_chat_LLM_Proxy` is considered an upstream component for this repository, not an internal part of the MCP backend.
Current rule:
- `mcp-1c-bridge` does not call LLM Proxy via HTTP;
- `mcp-1c-bridge` does not call LLM providers directly;
- `mcp-1c-bridge` only accepts correlation metadata and executes MCP tools as a backend to 1C.
Supported correlation metadata for secure tool calls:
- `trace_id`
- `project_id`
- `agent_id`
- `policy_id`
- `session_id`
If `trace_id` is not passed, the server generates it locally and writes it to the audit log.
## Read-only MVP
The current implementation corresponds to Phase 1 Secure MVP:
- The server is focused on read-only OData access;
- There is no raw OData tool for the agent;
- There is no `execute_1c_code`;
- There is no direct SQL;
- There are no posting/delete operations;
- `post_document_validated` does not conduct a document and is considered a forbidden tool in policy.
## Risk Levels
Phase 1 uses a risk model:
- `L0` — safe reading and metadata inspection
- `L1` — local analytics, explain/report/normalization without recording in 1C
- `L2` — potentially sensitive operations, forbidden in `read_only` mode
- `L3` — critical operations, always blocked
- `L4` — explicitly dangerous operations, always blocked
Typical interpretation:
- `L0`: `list_entities`, `get_inventory_auto`, `get_incoming_payments`
- `L1`: `payment_summary_by_counterparty`, `get_unpaid_customers_summary`, `explain_last_answer`
- `L2+`: write/post/delete/direct access scenarios
## Capabilities
Security policy uses capabilities as a level above specific tool names.
Examples of current capabilities:
- `read_metadata`
- `read_inventory`
- `read_payments`
- `read_receivables`
- `read_documents`
- `create_local_report`
- `normalize_input`
- `manage_local_knowledge`
- `route_read_only_requests`
A tool without declared capabilities in policy should not be executed.
## Policy File
The policy is located here:
```text
config/policy.yaml
```
The file specifies:
- `mode`
- `tools` allowlist
- `risk` per tool
- `capabilities` per tool
- `forbidden` denylist
- `output` settings
Main behavior:
- Default mode: `read_only`
- Unknown tool: `deny`
- Forbidden tool: `block`
- `L3`/`L4`: `block`
- `L2`: `deny` in `read_only`
## Audit Log
The audit log is append-only from the agent's perspective.
Default path:
```text
audit/audit.jsonl
```
Each record contains:
- `timestamp`
- `actor`
- `project_id`
- `agent_id`
- `policy_id`
- `session_id`
- `trace_id`
- `tool`
- `risk`
- `capabilities`
- `decision`
- `policy_version`
- `duration_ms`
- `error`
The audit log is created for both allowed and denied/blocked calls.
## Output Filter
Before returning the result to the MCP client, the server applies an output filter.
Phase 1 filter supports:
- `max_rows`
- Optional IIN/BIN masking
- Optional bank account masking
- Credential redaction
- Blocking external URLs in payload-like output fields
Filter settings are also specified in `config/policy.yaml`.
## Forbidden Operations
Phase 1 explicitly forbids such operations:
- `raw_odata`
- `query_entity`
- `execute_1c_code`
- `direct_sql`
- `delete_object`
- `post_document`
- `unpost_document`
- `change_posted_document`
- `change_closed_period`
- `external_http`
- `send_email`
- `upload_file`
- `disable_audit`
- `modify_policy`
- `post_document_validated`
This is a policy-level restriction and is intended specifically for Secure MVP.
## Architecture Flow
Current security flow:
```text
MCP client
-> MCP tool calls
-> Optional correlation metadata accepted
-> Startup-validated secure tool registration
-> Policy load
-> Allowlist / denylist check
-> Risk check
-> Capability check
-> Tool execution only if allowed
-> Output filter
-> Append-only audit log
-> Final MCP response
```
High-level architecture:
```text
User / MCP Client
|
v
FastMCP tools in core_server.py
|
v
SecureToolRunner
-> policy_loader
-> decision_engine
-> output_filter
-> audit_logger
|
v
Business read logic
-> odata.py
-> validation.py
-> knowledge.py
|
v
1C OData
```
Current actual flow:
```text
Open Interpreter / MCP client
-> Direct MCP call to this server
-> SecureToolRunner
-> 1C OData adapter
-> Output filter
-> Audit log
-> MCP response
```
Future intended flow:
```text
User query
-> AshybulakStroy_chat_LLM_Proxy
-> Model/provider decision
-> MCP call to mcp-1c-bridge with trace_id/project_id/agent_id/policy_id/session_id
-> SecureToolRunner
-> 1C OData adapter
-> Output filter
-> Audit log linked by trace_id
-> Final answer
```
Important:
- LLM Proxy Hub should live upstream;
- This MCP server only accepts correlation metadata and does not become an LLM client;
- This allows linking the audit trail between the proxy and MCP backend without transferring model-call logic to the bridge.
Startup policy validation:
```text
Registered MCP tools
-> Compare with config/policy.yaml
-> Require policy coverage
-> Require risk and capabilities for allowed tools
-> Reject forbidden+allowed conflicts
-> Fail startup on mismatch
```
## Server Capabilities
Main MCP tools:
- `get_server_status`
- `setup_wizard`
- `generate_1c_database_profile`
- `ask_1c`
- `list_entities`
- `describe_entity`
- `sample_entity`
- `search_metadata`
- `explore_live_entities`
- `discover_inventory_sources`
- `discover_payment_sources`
- `get_inventory_auto`
- `get_low_stock_items`
- `get_outgoing_payments`
- `get_incoming_payments`
- `payment_summary_by_counterparty`
- `get_unpaid_customers_summary`
- `get_overdue_unpaid_customers`
- `get_customer_payment_behavior_summary`
- `parse_inventory_report_text`
- `validate_inventory_report_text`
- `save_recipe`
- `list_recipes`
- `run_recipe`
- `list_capabilities`
- `get_capability`
- `buh_inspect`
- `parse_sales_invoice_text`
- `find_buh_entity`
- `normalize_sales_invoice`
- `validate_sales_invoice`
Blocked compatibility tools:
- `query_entity` is registered in code but blocked by policy in Secure Mode
- `post_document_validated` is registered as a compatibility guardrail but blocked by policy in Secure Mode
MCP resources:
- `buh://health`
- `buh://capabilities`
- `buh://entities`
- `buh://normalization/sales-invoice-template`
MCP prompts:
- `buh_reviewer`
- `buh_tester`
- `buh_analyst`
## Installation
```bash
git clone https://github.com/ashybulakstroy/ashybulakstroy-mcp-1c-bridge.git
cd ashybulakstroy-mcp-1c-bridge
python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env
```
On Windows PowerShell:
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
Copy-Item .env.example .env
```
Recommended Python version:
- Optimal: `3.11.x`
- Supported: `3.10+`
- `3.12` is also suitable and used in the current local environment
## `.env` Configuration
```env
ONEC_ODATA_URL=http://localhost/AccountingKazakhstan/odata/standard.odata
ONEC_USERNAME=odata_user
ONEC_PASSWORD=secret
ONEC_TIMEOUT_SECONDS=60
ONEC_VERIFY_SSL=true
BRIDGE_DB_PATH=./bridge_knowledge.sqlite3
BRIDGE_MAX_TOP=500
```
The 1C user for OData should be separate and read-only.
## Launch
The package publishes one script-entrypoint:
```bash
ashybulak-1c-bridge
```
This is a stdio MCP server. There are no separate CLI subcommands like `start`, `inspect`, or `init-project` in the current build.
## Connecting to MCP Client
```json
{
"mcpServers": {
"ashybulakstroy-1c": {
"command": "ashybulak-1c-bridge",
"env": {
"ONEC_ODATA_URL": "http://localhost/AccountingKazakhstan/odata/standard.odata",
"ONEC_USERNAME": "readonly_user",
"ONEC_PASSWORD": "password",
"ONEC_TIMEOUT_SECONDS": "60",
"ONEC_VERIFY_SSL": "true",
"BRIDGE_MAX_TOP": "500"
}
}
}
}
```
## Typical First Scenario
The user can work with plain text through `ask_1c`:
```text
Check connection to 1C.
Make a passport of the 1C database.
Find sources of balances.
Show commodity balances.
Where does the product end?
Explain the last answer.
```
For more accurate diagnostics, you can call tools directly:
- `setup_wizard`
- `generate_1c_database_profile`
- `discover_inventory_sources`
- `get_inventory_auto`
- `get_low_stock_items`
## Business Scenarios for Payments
The server now supports several read-only scenarios for payments and receivables:
- `who did we pay` on a date or for a period;
- `who paid us` on a date or for a period;
- `top clients` by incoming payments;
- `top suppliers` by outgoing payments;
- `who did not pay` and `who we sent invoices to, but they did not pay`;
- `debtor older than 3 days`;
- `typical_payment_days` — how many days a client usually pays an invoice.
Examples of phrases for `ask_1c`:
```text
Who did we pay for the period 2026-04-01 2026-04-30
Who paid us on the date 2026-04-24
Top clients for the period 2026-04-01 2026-04-30
Who did not pay within 3 calendar days
How many days does a client usually pay
```
New tools for these scenarios:
- `discover_payment_sources`
- `get_outgoing_payments`
- `get_incoming_payments`
- `payment_summary_by_counterparty`
- `get_unpaid_customers_summary`
- `get_overdue_unpaid_customers`
- `get_customer_payment_behavior_summary`
## Reconciliation with 1C Report
1. In 1C, generate an official report, for example, "Material Ledger".
2. Set the same filters as in the MCP request.
3. Copy the table part of the report.
4. Pass the text to `validate_inventory_report_text`.
Example:
```text
Reconcile balances with this report:
Product Warehouse Quantity Amount
Cement M400 Main Warehouse 100 250000
Sand Main Warehouse 50 30000
```
## Limitations and Security
- The server is focused on reading data through OData;
- The server does not create or conduct documents in the current runtime;
- `post_document_validated` is a guardrail stub and returns the status `validated_but_not_posted`;
- The results of `get_inventory_auto` and `get_low_stock_items` are heuristic and must be confirmed by a 1C report;
- Payment reports on payments and receivables are built using OData heuristics and must be reconciled with 1C reports on settlements;
- Overdue and `typical_payment_days` are calculated using the FIFO method by counterparty, this is a management calculation, not an official accounting register;
- Internal names of 1C objects cannot be hardcoded without checking through `$metadata`.
## Project Structure
```text
src/ashybulakstroy_mcp_1c_bridge/
core_server.py # main implementation of MCP tools/resources/prompts
mcp/server.py # stable facade entrypoint
odata.py # OData client, metadata discovery, inventory heuristics
knowledge.py # SQLite recipe storage
validation.py # parsing and reconciliation
normalization/ # document draft normalization helpers
validation_rules/ # document/business guardrails
```
## Testing
```bash
pip install -e .[dev]
python -m pytest -q
```
Audit log verification:
```bash
python scripts/verify_audit_log.py
```
GitHub Actions runs tests on `Python 3.10`, `3.11`, and `3.12`.
Details:
- `docs/testing.md`
- `docs/architecture.md`
- `docs/MCP_RESOURCES_PROMPTS_HTTP.md`
- `docs/DEMO_READONLY_SECURE_MODE.md`
- `docs/DEMO_PROMPTS.md`
## Project Status
The project is in a working state as an MCP read-only bridge for OData inspection, balances, payment reports, and reconciliation.
The document normalization and validation layer is already built-in, but actual recording and posting in 1C require a separate RPC adapter and explicit extension of the current runtime.
For demo and initial pilot, it is better to show:
- metadata inspection and setup;
- balances and low stock;
- incoming/outgoing payments;
- receivables and overdue;
- explain/reconciliation scenarios;
- audit log and blocked operations.
## Roadmap
See [Secure AI Bridge Roadmap](docs/ROADMAP_SECURE_AI_BRIDGE.md).
## License
MIT
