# CLAUDE.md

该文件为 Claude Code (claude.ai/code) 在此代码库中工作时提供指导。

## 架构概览

本项目是一个基于 Python 的模型上下文协议 (MCP) 服务器，用于与 Oracle 数据库进行交互。它允许客户端（如 AI 模型）通过一组定义的工具与 Oracle 数据库进行交互。

-   **`src/oracle_mcp_server/__init__.py`**: 这是服务器的主要入口点。它使用 `FastMCP` 定义和公开工具，还负责加载环境变量和初始化服务器。
-   **`src/oracle_mcp_server/oracle_tools.py`**: 该文件包含数据库交互的核心逻辑。它管理 Oracle 数据库连接池，并使用 `oracledb` 库实现列出表、描述表和执行查询的实际功能。
-   **`pyproject.toml`**: 定义项目依赖项和入口点（`main` 和 `dev`）。
-   **`package.json`**: 定义了用于运行 MCP 检查器的脚本。

服务器公开了以下工具：
-   `list_tables`: 列出数据库中的所有表。
-   `describe_table`: 提供给定表的结构信息。
-   `execute_DQL`: 执行 `SELECT` 查询。

## 常用开发命令

本项目使用 `uv` 进行 Python 包管理，使用 `pnpm` 进行 Node.js 包管理。

### 安装

1.  **安装 Python 依赖：**
    ```bash
    uv pip install -e .
    ```

2.  **安装 Node.js 依赖（用于检查器）：**
    ```bash
    pnpm install
    ```

### 环境变量

在运行服务器之前，您必须设置以下环境变量。您可以在项目根目录中创建一个 `.env` 文件来配置它们。

-   `ORACLE_CONNECTION_STRING`: 您的 Oracle 数据库连接字符串。
    -   格式: `username/password@hostname:port/service_name`
-   `LIB_DIR`: 您的 Oracle Instant Client 目录的路径。

### 运行服务器

-   **用于开发（支持热重载和优雅关闭）：**
    ```bash
    uv run dev
    ```

-   **用于生产：**
    服务器旨在通过 `mcp.json` 配置文件中指定的命令运行，通常使用 `uvx`。
    ```bash
    uvx oracle11g-mcp-server
    ```

### 检查 MCP 服务器

要查看可用的工具及其结构，您可以使用 MCP 检查器：

```bash
pnpm run inspector
```
