# tinydb-emcipi – Detailed Guide
This document preserves the in-depth information removed from the streamlined `README.md`.
---
## Design Goals
* **Configuration-Driven** – One JSON config file defines sandbox path, log path and default DBs.
* **Explicit Initialization** – Every major module exposes an `init_*()` call; nothing heavy happens at import time.
* **Canonical Logging** – `utils/serverlogging.py` centralises log setup; all modules log an info when initialised.
* **Schema Validation** – Records are checked against a TinyDB-stored JSON Schema before insert/update.
* **DRY / Separation of Concerns** – No hidden fallbacks or hard-coded defaults.
## Module Overview
| Module | Responsibility |
|--------|----------------|
| `utils/db.py` | TinyDB CRUD + validation helpers |
| `utils/schema.py` | JSON Schema storage & retrieval |
| `utils/emcipi.py` | MCP tool wrappers, active-DB handling |
| `utils/config.py` | Load config values via `get_config(key)` |
| `utils/serverlogging.py` | Log formatter & convenience wrappers |
| `main.py` | Entry-point: initialise modules and start FastMCP |
## MCP Tool Behaviour
### Active Database Workflow
1. Client lists DBs with `list_databases_tool`.
2. Client selects one using `switch_active_db_tool` (sets `_ACTIVE_DB`).
3. All other tools operate on `_ACTIVE_DB` exclusively.
If `_ACTIVE_DB` is `None`, tools respond with an error prompting to switch; `search_records_tool` and others now also include the full schema in the result for smarter agent retries.
### Error Guidance Patterns
* Tool responses embed `tip` keys suggesting next steps.
* Validation failures include the missing/invalid field and link back to `get_database_info_tool`.
## Docker Details
The top-level `docker-compose.yml` mounts the repo into `/app` inside a `python:3.13` container, installs dependencies, then runs `python -m main`.
## Expanded Project Structure
```
config/ # server config JSON
logs/
sandbox/db/ # TinyDB files live here
sandbox/dbschema/ # optional sample schema files
utils/
api.py # legacy REST shim (optional)
db.py
schema.py
emcipi.py # MCP wrapper
config.py
serverlogging.py
main.py
requirements.txt
Docker-compose.yml
```
## Roadmap Extract
* Field statistics and schema analysis in `get_database_info_tool`.
* Suggest-as-you-type query completion via schema.
* Test suite coverage ≥ 90 %.
---
For any questions or contributions, open an issue or PR.