Metadata-Version: 2.4
Name: couchdb-mcp-server
Version: 0.1.0
Summary: Local read-only Model Context Protocol server for Apache CouchDB
Keywords: couchdb,mcp,model-context-protocol
License-Expression: Apache-2.0
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Typing :: Typed
Requires-Dist: httpx>=0.28,<1
Requires-Dist: mcp>=1.12,<2
Requires-Dist: pydantic>=2.10,<3
Requires-Dist: pydantic-settings>=2.7,<3
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# CouchDB MCP Server

CouchDB MCP Server is an open-source Python Model Context Protocol server for Apache CouchDB.

The project is in early development. Version `0.1.0 Read-Only Preview` is implemented in source but has not been published as a release package yet. Published packages and release installation commands should not be assumed to exist until they are documented in a release.

## 0.1 Scope

Version `0.1.0 Read-Only Preview` is a local, strictly read-only MCP server for Apache CouchDB 3.x.

The approved version 0.1 constraints are:

- local `stdio` MCP transport only;
- one CouchDB instance per server process;
- no writes, administration, replication, attachments, dashboard, embedded AI, or remote MCP server;
- compact, bounded, structured, model-friendly responses;
- security controls enforced by implementation, not only documentation.

See [docs/SCOPE_0_1.md](docs/SCOPE_0_1.md) for the contributor-facing scope summary.

## 0.1 Tools

Version 0.1 exposes exactly these nine product tools:

1. `get_server_status`
2. `list_databases`
3. `get_database_info`
4. `get_document`
5. `list_documents`
6. `query_documents`
7. `list_indexes`
8. `explain_query`
9. `inspect_database_structure`

The `query_documents` implementation supports a safe Mango subset: `selector`, `fields`, `limit`, `bookmark`, `sort`, and `use_index`. It does not expose arbitrary Mango options.

The `list_indexes` implementation lists Mango index metadata for authorized databases. It does not create, delete, or modify indexes.

The `explain_query` implementation explains a controlled Mango query plan for an authorized database. It does not return matching documents or expose raw design documents.

The `inspect_database_structure` implementation infers probable field structure from a bounded document sample. It reports field paths, observed types, occurrence counts, and frequencies without returning example values.

All nine approved version 0.1 tools are implemented in source. Release readiness still depends on packaging, verification, and publication checks.

## Not In 0.1

The following are explicitly outside the approved 0.1 scope:

- document creation, updates, deletion, or bulk writes;
- database creation or deletion;
- index creation or deletion;
- user, permission, cluster, compaction, replication, or CouchDB configuration administration;
- arbitrary CouchDB endpoint wrappers such as `execute_request`, `call_endpoint`, or `send_http_request`;
- attachments, revision history browsing, MapReduce views, and continuous changes feeds;
- Streamable HTTP transport, public remote MCP hosting, OAuth, OIDC, SSO, or remote sessions;
- multiple CouchDB instances in one server process;
- dashboard, desktop UI, embedded language model, embeddings, semantic search, autonomous agents, and automatic index creation.

Ideas outside 0.1 should be discussed as future-version candidates rather than implemented directly.

## Security Direction

The intended 0.1 security model includes:

- database allowlists applied before CouchDB database requests;
- CouchDB system databases hidden by default;
- TLS certificate verification enabled by default for HTTPS;
- no credentials in MCP responses, exceptions, logs, URLs, snapshots, or committed files;
- response-size, JSON-depth, document-count, timeout, and pagination limits;
- normalized errors without internal stack traces;
- stdout reserved for MCP `stdio` protocol traffic, with diagnostics sent to stderr.

## Documentation

Current project references:

- [0.1 Scope Summary](docs/SCOPE_0_1.md)
- [Functional Scope 0.1](docs/product/reference/Functional_Scope_CouchDB_MCP_Server_0.1.md)
- [Official Vision](docs/product/reference/Official_Vision_CouchDB_MCP_Server.md)

## Local Development

The Python project skeleton is managed with `uv`.

Current local checks:

```bash
uv sync
uv run ruff format --check .
uv run ruff check .
uv run mypy src tests
uv run pytest
```

Optional CouchDB integration tests are disabled by default. They require a local CouchDB
instance and create then delete a dedicated test database:

```powershell
$env:COUCHDB_MCP_RUN_INTEGRATION = "1"
$env:COUCHDB_MCP_COUCHDB_URL = "url"
$env:COUCHDB_MCP_COUCHDB_USERNAME = "username"
$env:COUCHDB_MCP_COUCHDB_PASSWORD = "password"
$env:COUCHDB_MCP_INTEGRATION_DATABASE = "couchdb_mcp_tools_integration"
uv run pytest tests/test_couchdb_tools_integration.py
uv run pytest tests/test_mcp_stdio_integration.py
```

The executable module runs a local `stdio` MCP server and exposes the nine approved version 0.1 tools.

## Compatibility

For version 0.1 public preview, compatibility has been verified with MCP Inspector and the official MCP Python SDK `stdio` client.

Broader MCP host compatibility remains pending and will be validated after the public preview release.

## Configuration

Configuration is loaded from environment variables with the `COUCHDB_MCP_` prefix and,
for local development, from an optional `.env` file.

See [.env.example](.env.example) for the current configuration surface.

Configuration validates:

- CouchDB base URL without embedded credentials;
- optional username and password, with password treated as a secret;
- database allowlist parsing and validation;
- system database access disabled by default;
- positive limits for documents, schema inspection, response size, JSON depth, and timeout;
- maximum limits greater than or equal to default limits;
- TLS verification enabled by default.

## Contributing

Contributions should stay within the approved 0.1 scope unless an explicit product decision changes that scope.

Before proposing a change, read [CONTRIBUTING.md](CONTRIBUTING.md) and [docs/SCOPE_0_1.md](docs/SCOPE_0_1.md).

## License

This project is licensed under the Apache License 2.0. See [LICENSE](LICENSE).
