Metadata-Version: 2.4
Name: mongodb-mcp-vn
Version: 0.1.4
Summary: Safe MongoDB MCP Server
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: mcp<2,>=1.28
Requires-Dist: pymongo<4.11,>=4.10
Requires-Dist: pydantic>=2.8.0
Requires-Dist: pydantic-settings>=2.4.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: dev
Requires-Dist: mongomock<5,>=4.3; extra == "dev"
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"

# MongoDB MCP VN

English | [Tiếng Việt](#tiếng-việt)

`mongodb-mcp-vn` is a Python MCP server for bounded MongoDB discovery, read, and
explicitly guarded mutation operations. It returns MongoDB Extended JSON and never
returns a configured connection URI or driver exception details.

## Install and run

Install the released package:

```sh
uv tool install mongodb-mcp-vn
```

Or, from a source checkout:

```sh
cd uvx/mongodb
uv sync --extra dev
```

Set a least-privilege URI outside source control. This local example contains no
credentials:

```sh
export MONGO_URI='mongodb://localhost:27017'
```

### stdio (default)

Use stdio for a local MCP client such as Codex or Claude Desktop:

```sh
MCP_TRANSPORT=stdio mongodb-mcp-vn
```

The equivalent source command is `uv run mongodb-mcp-vn`.

### MCP client JSON configuration (stdio)

Add this to your Codex or Claude Desktop MCP configuration. Do not set
`MCP_TRANSPORT`; stdio is the default.

```json
{
  "mcpServers": {
    "mongodb-mcp-vn": {
      "command": "uvx",
      "args": ["mongodb-mcp-vn"],
      "env": {
        "MONGO_URI": "mongodb://localhost:27017",
        "MONGO_ALLOW_WRITE": "false"
      }
    }
  }
}
```

Set `MONGO_ALLOW_WRITE` to `true` only when the MCP client must create, update,
delete documents, or drop a collection; restart the client after changing it.

Tool inputs are direct JSON fields: call `mongodb_ping` with `{}`, and call
`mongodb_list_databases` with `{"limit": 50}`. Do not wrap them in `params`.

### Streamable HTTP

Use streamable HTTP only behind an appropriate network boundary. The defaults are
`127.0.0.1:8005`; `streamable_http` is accepted as an alias.

```sh
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8005 mongodb-mcp-vn
```

`MCP_PORT` must be an integer from 1 through 65535. Unsupported transports fail at
startup rather than silently changing transport.

## Tools

All collection and database names preserve the supplied bytes; blank-only names are
rejected. Read tools have a bounded `limit` (maximum 100) and return Extended JSON.

| Tool | Operation |
| --- | --- |
| `mongodb_ping` | Check connectivity and report MongoDB server version. |
| `mongodb_list_databases` | Page through accessible database metadata. |
| `mongodb_list_collections` | Page through collections in one database. |
| `mongodb_describe_collection` | Return collection options, count, sampled fields, and indexes. |
| `mongodb_list_indexes` | Page through index specifications. |
| `mongodb_find_documents` | Bounded `find` with Extended JSON filter, projection, and sort. |
| `mongodb_aggregate` | Bounded read aggregation; `$out` and `$merge` are forbidden. |
| `mongodb_create_collection` | Create one collection after the write gate passes. |
| `mongodb_create_index` | Create one index after the write gate passes. |
| `mongodb_insert_documents` | Insert a non-empty Extended JSON document array after the write gate passes. |
| `mongodb_update_documents` | Run explicit `update_one` or `update_many` after the write gate passes. |
| `mongodb_delete_documents` | Run explicit `delete_one` or `delete_many` after the write gate passes. |
| `mongodb_drop_collection` | Drop exactly one collection after the write gate and exact confirmation pass. |

## Security and writes

- `MONGO_URI` is required; keep it in your shell, secret manager, or MCP-client
  environment—not in this README, source, or logs.
- Writes are disabled by default. Set `MONGO_ALLOW_WRITE=true` **before starting**
  the server only when a mutation is intended; restart to return to the safe default.
- `mongodb_drop_collection` additionally requires `confirmation` to be byte-for-byte
  identical to `collection_name`, including whitespace and case.
- Use a MongoDB role limited to the required databases and actions. This server does
  not provide generic commands, database drops, user/role administration, or shutdown.
- Extended JSON inputs are shape-checked before client acquisition; invalid requests
  and driver failures are redacted instead of echoing secrets.

## Compatibility

The server supports MongoDB deployments from 3.6 onward for the discovery/read
features used here; use a current supported MongoDB release for production security
updates. MongoDB 5.0+ x86_64 server binaries require AVX. On a non-AVX host, run a
compatible pre-5.0 MongoDB deployment where it is still appropriate for your risk
profile, move the database to supported hardware, or use a compatible managed service;
this MCP server cannot bypass the database binary's CPU requirement. See MongoDB's
[production notes](https://www.mongodb.com/docs/manual/administration/production-notes/).

## Fixed local evaluation fixture

The ten independent, read-only questions in `evaluations/mongodb_read_only.xml` use a
fixed local database named `mongodb_mcp_evaluation`. Each requires multi-tool,
cross-collection exploration (metadata/index inspection plus bounded reads or
aggregations), rather than a single lookup. Seed it only in a disposable local MongoDB
instance before an evaluation; it is not created by the MCP server.

| Collection | Fixed documents |
| --- | --- |
| `customers` | `{customer_id: "c-001", name: "Ada", tier: "bronze"}`, `{customer_id: "c-002", name: "Binh", tier: "gold"}`, `{customer_id: "c-003", name: "Chi", tier: "gold"}` |
| `products` | `{sku: "T-100", name: "Tea", category: "beverage", price: 12}`, `{sku: "C-200", name: "Coffee", category: "beverage", price: 20}`, `{sku: "N-300", name: "Notebook", category: "stationery", price: 8}` |
| `orders` | `{order_id: "o-1001", customer_id: "c-001", sku: "T-100", quantity: 2, amount: 24, status: "paid", created_at: "2024-01-10"}`, `{order_id: "o-1002", customer_id: "c-002", sku: "C-200", quantity: 1, amount: 20, status: "paid", created_at: "2024-01-11"}`, `{order_id: "o-1003", customer_id: "c-001", sku: "N-300", quantity: 3, amount: 24, status: "pending", created_at: "2024-02-01"}`, `{order_id: "o-1004", customer_id: "c-003", sku: "T-100", quantity: 5, amount: 60, status: "paid", created_at: "2024-02-02"}`, `{order_id: "o-1005", customer_id: "c-002", sku: "N-300", quantity: 1, amount: 8, status: "cancelled", created_at: "2024-02-03"}` |

Create only these fixed indexes for the fixture: the default `_id_` indexes plus
`orders.order_id` as unique index `order_id_1`, `orders.(customer_id, created_at)` as
`customer_id_1_created_at_-1`, and `orders.status` as `status_1`.

## Release

Build and publish only from a clean, reviewed checkout. `publish.sh` and `publish.bat`
accept no token argument, contain no credential, and use only the environment variable
`UV_PUBLISH_TOKEN`:

```sh
export UV_PUBLISH_TOKEN='set-this-in-your-secret-manager-or-shell'
./publish.sh
```

Do not commit, print, or replace the token.

## Tiếng Việt

`mongodb-mcp-vn` là MCP server Python cho các thao tác khám phá/đọc MongoDB có giới
hạn và các thao tác ghi được bảo vệ rõ ràng. Server trả về MongoDB Extended JSON và
không trả lại URI đã cấu hình hoặc chi tiết lỗi từ driver.

### Cài đặt và transport

```sh
uv tool install mongodb-mcp-vn
export MONGO_URI='mongodb://localhost:27017'
MCP_TRANSPORT=stdio mongodb-mcp-vn
```

`stdio` là mặc định cho MCP client cục bộ. Với Streamable HTTP, dùng biên mạng phù hợp:

```sh
MCP_TRANSPORT=streamable-http MCP_HOST=127.0.0.1 MCP_PORT=8005 mongodb-mcp-vn
```

`MCP_PORT` phải nằm trong 1–65535.

### Cấu hình JSON cho MCP client (stdio)

Thêm block JSON sau vào cấu hình MCP của Codex hoặc Claude Desktop. Không cần khai báo
`MCP_TRANSPORT` vì `stdio` là mặc định:

```json
{
  "mcpServers": {
    "mongodb-mcp-vn": {
      "command": "uvx",
      "args": ["mongodb-mcp-vn"],
      "env": {
        "MONGO_URI": "mongodb://localhost:27017",
        "MONGO_ALLOW_WRITE": "false"
      }
    }
  }
}
```

Chỉ đổi `MONGO_ALLOW_WRITE` thành `true` khi cần tạo/sửa/xóa dữ liệu; restart MCP client
sau khi đổi biến môi trường.

### Công cụ

| Công cụ | Mục đích |
| --- | --- |
| `mongodb_ping` | Kiểm tra kết nối và phiên bản MongoDB. |
| `mongodb_list_databases` / `mongodb_list_collections` | Liệt kê có phân trang database hoặc collection được phép truy cập. |
| `mongodb_describe_collection` / `mongodb_list_indexes` | Xem metadata, mẫu schema, số lượng và index có giới hạn. |
| `mongodb_find_documents` / `mongodb_aggregate` | Đọc có giới hạn; aggregate chặn `$out` và `$merge`. |
| `mongodb_create_collection` / `mongodb_create_index` / `mongodb_insert_documents` | Tạo collection/index hoặc chèn document sau write gate. |
| `mongodb_update_documents` / `mongodb_delete_documents` | Chỉ chạy rõ ràng `update_one`/`update_many` hoặc `delete_one`/`delete_many`. |
| `mongodb_drop_collection` | Xóa một collection khi write gate và xác nhận chính xác đều hợp lệ. |

### Bảo mật và ghi dữ liệu

- `MONGO_URI` là bắt buộc; đặt trong secret manager hoặc biến môi trường, không lưu vào
  mã nguồn, tài liệu, hay log.
- Ghi bị tắt mặc định. Chỉ đặt `MONGO_ALLOW_WRITE=true` trước khi khởi động khi thật sự
  cần ghi; khởi động lại không có biến này để trở về chế độ an toàn.
- Khi xóa collection, `confirmation` phải khớp chính xác từng ký tự với
  `collection_name`, bao gồm hoa/thường và khoảng trắng.
- Dùng MongoDB role tối thiểu cần thiết. Không có lệnh tổng quát, xóa database, quản lý
  user/role, hoặc shutdown.

### Tương thích và phát hành

Server hỗ trợ MongoDB 3.6+ cho các khả năng khám phá/đọc nêu trên. MongoDB 5.0+ trên
`x86_64` yêu cầu AVX; máy không có AVX cần dùng deployment trước 5.0 phù hợp với chính
sách vận hành, chuyển sang phần cứng được hỗ trợ, hoặc dịch vụ managed tương thích.
MCP server không thể vượt qua giới hạn CPU của binary MongoDB.

`publish.sh` và `publish.bat` chỉ đọc `UV_PUBLISH_TOKEN` từ môi trường; không truyền,
ghi, hay thay đổi token trong script. Bộ fixture cố định và 10 câu hỏi chỉ-đọc nằm ở
`evaluations/mongodb_read_only.xml`.
