Content
# 1c-buddy-mcp
Lightweight standalone MCP server for working with [1C.ai](https://code.1c.ai) from Codex and other MCP clients. Runs directly in Python via stdio: without Docker, web chat, OpenAI-compatible gateway, and separate HTTP server.
The project is based on the MCP/API implementation [`ROCTUP/1c-buddy`](https://github.com/ROCTUP/1c-buddy). The last checked upstream commit: [`7f2b0305cd80e3a9f2cebb2dc69603fd7c7ab054`](https://github.com/ROCTUP/1c-buddy/commit/7f2b0305cd80e3a9f2cebb2dc69603fd7c7ab054).
## Tool List
| Tool | Purpose |
| --- | --- |
| `ask_1c_ai` | General questions about the 1C platform and practical scenarios |
| `explain_1c_syntax` | Explanation of 1C object, method, type, or construct |
| `check_1c_code` | Syntax check or code review of BSL code |
| `modify_1c_code` | Changing BSL code according to an explicit task |
| `search_1c_documentation` | Search in 1C:Enterprise documentation |
| `search_its` | Search in ITS knowledge base |
| `fetch_its` | Getting a document or section of ITS by `id` |
| `diff_1c_documentation_versions` | Comparing documentation between platform versions |
## Requirements
- Python 3.10 or later;
- Git;
- Valid 1C.ai token in the `ONEC_AI_TOKEN` variable;
- Codex or another MCP client with stdio support.
## Installation in Windows PowerShell
```powershell
git clone https://github.com/VVi3ard/1c-buddy-mcp.git "$HOME\.codex\mcp\1c-buddy-mcp"
Set-Location "$HOME\.codex\mcp\1c-buddy-mcp"
py -m venv .venv
& .\.venv\Scripts\python.exe -m pip install --upgrade pip
& .\.venv\Scripts\python.exe -m pip install .
```
Save the token in the user environment and restart Codex:
```powershell
[Environment]::SetEnvironmentVariable("ONEC_AI_TOKEN", "YOUR_TOKEN", "User")
```
Do not add the token to Git, README, or public configurations.
## Installation in Linux/macOS
```bash
git clone https://github.com/VVi3ard/1c-buddy-mcp.git ~/.codex/mcp/1c-buddy-mcp
cd ~/.codex/mcp/1c-buddy-mcp
python3 -m venv .venv
./.venv/bin/python -m pip install --upgrade pip
./.venv/bin/python -m pip install .
export ONEC_AI_TOKEN='YOUR_TOKEN'
```
Use a secure storage or shell configuration with limited access to store the variable persistently.
## Connection to Codex
Add to `C:\Users\<username>\.codex\config.toml`:
```toml
[mcp_servers.onec-ai-1c]
command = 'C:\Users\<username>\.codex\mcp\1c-buddy-mcp\.venv\Scripts\python.exe'
args = ["-m", "onec_buddy_mcp"]
cwd = 'C:\Users\<username>\.codex\mcp\1c-buddy-mcp'
startup_timeout_sec = 30
[mcp_servers.onec-ai-1c.env]
ONEC_AI_UI_LANGUAGE = "russian"
ONEC_AI_TIMEOUT = "30"
MCP_TOOL_CALL_MODE = "direct"
```
The token is intentionally omitted from TOML: the process receives `ONEC_AI_TOKEN` from the user environment. Restart Codex after changing the configuration.
For Linux/macOS, specify absolute paths to `.venv/bin/python` and the repository directory.
## Verification
Install development dependencies and run unit tests:
```powershell
& .\.venv\Scripts\python.exe -m pip install -e ".[dev]"
& .\.venv\Scripts\python.exe -m pytest -m "not live" -q
```
Live tests are performed only on explicit request and use the environment token:
```powershell
$env:RUN_LIVE_TESTS = "1"
& .\.venv\Scripts\python.exe -m pytest -m live -q
```
After restarting Codex, check the MCP tool list and perform, for example:
- `ask_1c_ai`: "What is ТаблицаЗначений?";
- `check_1c_code`: syntax check of a short procedure;
- `search_1c_documentation`: search for `HTTPСоединение` for the required version.
## Settings
| Variable | Required | Default Value |
| --- | --- | --- |
| `ONEC_AI_TOKEN` | yes | — |
| `ONEC_AI_BASE_URL` | no | `https://code.1c.ai` |
| `ONEC_AI_TIMEOUT` | no | `30` |
| `ONEC_AI_UI_LANGUAGE` | no | `russian` |
| `ONEC_AI_PROGRAMMING_LANGUAGE` | no | empty |
| `DEFAULT_SSL_VERSION` | no | empty |
| `DEFAULT_1C_CONFIGURATION` | no | empty |
| `MCP_TOOL_INPUT_MIN_LENGTH` | no | `4` |
| `MCP_TOOL_INPUT_MAX_LENGTH` | no | `100000` |
| `MCP_TOOL_CALL_MODE` | no | `direct` |
| `ONEC_AI_INCLUDE_LIMITATIONS` | no | `true` |
`direct` calls specialized upstream tools for syntax, documentation, and ITS. `standard` formulates a regular request to 1C.ai and is useful as a compatibility mode during upstream changes.
Each tool's successful response contains sections `Ответ`, `Ограничения инструмента`, and `Требуемая проверка`. Limitations are formed by the MCP server, not the AI model, and take into account the purpose of a specific tool. To return responses in their original form, set `ONEC_AI_INCLUDE_LIMITATIONS=false`.
## Update from Upstream
Projects have different structures and are not intended for a full `git merge`. Changes in the 1C.ai API and MCP tools are transferred controllably according to the instructions [docs/UPDATING_FROM_UPSTREAM.md](docs/UPDATING_FROM_UPSTREAM.md).
## Troubleshooting
- `ONEC_AI_TOKEN` missing: set the user variable and fully restart Codex so that the new process receives the environment.
- HTTP 401/403: the token is rejected by 1C.ai or not passed to the process.
- HTTP 422: upstream changed the payload; compare the actual `1c-buddy` modules according to the update guide.
- The server does not appear in Codex: check absolute `command`, `cwd`, presence of `.venv`, and run `python -m onec_buddy_mcp` manually. In the working stdio mode, the process waits for MCP input and does not print anything to stdout.
- ITS search does not return data: access depends on account capabilities and current upstream tools of 1C.ai.
## Security
- The token is stored as `SecretStr` and is not included in the repr of settings;
- MCP errors do not return the `Authorization` header;
- Logs are written to stderr, stdout is reserved for MCP;
- `.env`, virtual environments, and test artifacts are excluded from Git.
## License and Authorship
The project is distributed under [GNU AGPL v3](LICENSE). The implementation of API interaction, tool schemes, and part of the prompt logic are derived from [`ROCTUP/1c-buddy`](https://github.com/ROCTUP/1c-buddy), also distributed under GNU AGPL v3. The new project is not an official product of "1С" company.
