内容
# 数据专业版
为您的数据库编目，嵌入文档，跨领域提问，并通过MCP（模型上下文协议）连接Cursor或Claude等智能代理。
采用React，FastAPI，Postgres + pgvector和Mistral或Ollama构建。
## 目录数据库（必需）
数据专业版在您自己的**PostgreSQL**数据库中存储**目录元数据和RAG嵌入**（领域，数据集，`knowledge_chunks`，pgvector）。在`.env`中配置连接 — 这与您稍后在目录中附加的可选仓库/源数据库是分开的。
**→ [设置您的目录数据库](docs/catalog-database.md)** — 创建Postgres + pgvector，设置`DATABASE_URL`，运行迁移。
Docker Compose包含用于本地开发的Postgres；对于您自己的RDS或现有的Postgres，请遵循相同的文档。
## AWS部署（可选）
生产部署目标是**Amazon Web Services（AWS）** — **ECS Fargate**，**ECR**，**RDS**和**Secrets Manager**。模板位于`deploy.example/`；复制到gitignored的`deploy/`中，并包含您的账户设置。
**→ [部署到AWS ECS](docs/deploy-ecs.md)** — 构建镜像，推送到ECR，在Fargate上运行。
本地开发仅使用Docker Compose；使用该应用程序不需要AWS。
## 开始使用
```bash
git clone https://github.com/siva18k/datapro_ai.git data-pro
cd data-pro
cp .env.example .env
# 在.env中设置MISTRAL_API_KEY — 或设置DEFAULT_LLM_BACKEND=ollama
# 可选：cp saved_db_connections.json.example saved_db_connections.json
docker compose up --build
```
然后打开UI（默认端口**5173**）。服务URL和端口在[docs/installation.md](docs/installation.md)中。
如果您更喜欢本地开发而不是Docker：
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cd web && npm install
```
前端位于web文件夹中，因此使用`cd web && npm run dev`（或从存储库根目录使用`npm --prefix web run dev`）。存储库根目录不包含自己的package.json。
## 功能
**数据目录** — 领域，数据集，Postgres连接，文件上传。
**提问** — 在您的文档（RAG）或结构化SQL上进行聊天，当您连接了Postgres数据集时。
**分析** — 从普通英文构建仪表板。
**RAG** — 分片设置和嵌入摄入。
**MCP** — 相同的知识库，但可从Cursor / Claude Desktop调用。每个领域的**工具**，**资源**和**提示**遵循[模型上下文协议](https://modelcontextprotocol.io/)（工具=动作，资源=只读上下文，提示=模板）。参见[MCP](docs/mcp.md)以获取客户端设置和完整的目录。
如果RAG或MCP对您来说是新的，[docs/concepts.md](docs/concepts.md)会在几分钟内解释两者。
### MCP：功能位置及扩展难度
| 内容 | 位置 | 重启MCP？ |
|------|--------|--------------|
| 工具/资源**代码** | `mcp_server.py`（`@mcp.tool`，`@mcp.resource`） | 是 |
| 名称，描述，启用/禁用 | `mcp_registry.py` + `mcp_registry.json` | 是（提示）；元数据在重启后获取 |
| 领域日历/词汇表/sql-notes**内容** | 数据库（`domain_reference_docs`）或`PUT /api/domains/{id}/references/…` | 否 |
| 模式资源 | 从**数据目录**（数据集，表，列）生成 | 否 |
| 每个领域使用的功能 | **MCP**页面 → 领域绑定（或数据库中的`mcp_bindings`） | 否 |
| 每个领域的**本地提示** | `domain_prompts`表 + MCP UI | 否 |
**我们是否与行业标准对齐？** 基本上是的。数据专业版正确使用了MCP的三个基本元素：**资源**用于只读上下文（模式，日历，词汇表），**工具**用于具有副作用或计算的动作（`search_documents`，`resolve_time_period`），以及**提示**作为可重用的模板。引用资源由**主机应用程序**（Ask/Analytics）在绑定时附加 — 这符合生产MCP主机控制上下文的方式，而不是让模型临时提取所有内容。可选的库存URI仅在规划器请求时加载。与“纯粹”的MCP服务器相比：一些引用预览直接从API/目录中提供（因此即使在MCP重启之前也有效），领域绑定是基于MCP的多租户产品应用层模式。
**添加工具或资源是否困难？** 通常**否**，对于此代码库：
- **简单（无Python）：** 更改领域引用markdown，绑定/解绑定UI中的功能，添加**本地**提示，在`mcp_registry.json`中编辑全局提示文本。
- **适中（~30–60分钟）：** 添加新的内置**工具**或**资源** — 在`mcp_registry.py`中添加一个条目，在`mcp_server.py`中添加一个处理程序，重启MCP，在MCP页面上绑定。遵循现有模式（`list_domain_sources`，`ragpro://domains/{domain}/calendar`）。
- **更多工作：** 将新工具连接到Ask**规划器**，使其自动调用，或添加Ask自动附加的**引用**资源（还需更新`mcp_reference_service.py`和`catalog_db.py`中的`DEFAULT_MCP_BINDINGS`）。
外部MCP服务器（例如`email_mcp_server.py`）在MCP页面上注册并绑定，如内置服务器 — 无需更改`mcp_server.py`。
**→ 完整指南：** [docs/mcp.md](docs/mcp.md) — 工具，资源，提示，环境变量和逐步扩展。
## 文档
- [docs/guide.md](docs/guide.md) — 索引
- **[贡献与约定](docs/contributing.md)** — 主题，机密，文档，UI一致性
- **[目录数据库](docs/catalog-database.md)** — 元数据 + RAG Postgres设置（必需）
- [安装](docs/installation.md) — 设置和脚本
- [机密](docs/secrets.md) — `.env`和保存的连接（仅在git中存储模板）
- [Docker](docs/docker.md) — 组合，服务，主机上的Ollama
- [部署到AWS ECS（Fargate）](docs/deploy-ecs.md) — **AWS**生产模板（`deploy.example/` → 本地`deploy/`）
- [用户指南](docs/user-guide.md) — 目录，摄入，提问
- [MCP](docs/mcp.md) — 服务器和客户端配置
- [架构](docs/architecture.md) — 各部分如何组合
- [故障排除](docs/troubleshooting.md) — 出现问题时
演示仓库SQL：[docs/finance-data-guide.md](docs/finance-data-guide.md)
## 保密
请勿提交真实的API密钥，生产数据库主机，密码，TLS证书或个人AWS部署文件。这些属于`.env`，`saved_db_connections.json`，`deploy/`和`certs/` — 所有这些都被git忽略。参见[docs/secrets.md](docs/secrets.md)和[docs/deploy-ecs.md](docs/deploy-ecs.md)。
`localhost` / `127.0.0.1`网址在文档中仅为本地开发默认值，而不是机密。
## 防止意外提交机密
存储库已经git忽略了`.env`和相关文件。为了添加额外的本地防护，您可以启用捆绑的pre-commit钩子，以阻止暂存`.env`文件：
1. 为此存储库启用钩子目录：
```bash
cd /path/to/repo
git config core.hooksPath .githooks
```
2. 钩子将中止包含`.env`或`.env.*`的暂存更改的提交。这是一个本地防护 — 建议在每台开发人员机器上启用它。
如果`.env`以前被意外提交，请从历史记录中删除它并轮换任何公开的机密（不要仅依赖历史记录重写）。
## 布局
```
api/ FastAPI后端
web/ React UI
docs/ 文档
migrations/ SQL模式
scripts/ migrate.py, dev.sh
mcp_server.py MCP服务器（工具，资源，提示）
mcp_registry.py MCP元数据默认值；mcp_registry.json覆盖
mcp_reference_service.py 领域引用资源内容（模式，日历，...）
docker-compose.yml
deploy.example/ AWS ECS部署模板（复制到gitignored deploy/）
sample_docs/ 示例文件
```
## 许可证
MIT — 参见[LICENSE](LICENSE)。克隆并随意使用；只有存储库所有者才能将更改推送到上游。
## 手动服务器启动序列
在本地运行所有内容（非Docker）时使用这些命令。
1. 确保您的目录Postgres已经运行，并可以通过`.env`（`DATABASE_URL`或`PG*`值）访问。
2. 激活Python环境（存储库根目录）：
```bash
source .venv/bin/activate
```
3. 运行目录迁移（存储库根目录）：
```bash
python scripts/migrate.py
```
4. 启动API服务器（存储库根目录）：
```bash
uvicorn api.main:app --reload --host 127.0.0.1 --port 8080
```
5. 启动MCP服务器（新终端，存储库根目录）：
```bash
source .venv/bin/activate
python mcp_server.py
```
6. 启动Web UI（新终端）：
```bash
cd web && npm run dev
```
7. 可选（仅在使用Ollama后端时）：
```bash
ollama serve
```
