AI Data Analysis Platform

人工智能数据分析平台

可通过生成AI进行数据分析的平台。通过MCP服务器为生成AI提供Jupyter环境下的分析执行和数据目录管理。

主要特征

• 工作区隔离 -为每个聊天（AI对话）提供独立的工作空间。文件和内核不会干扰其他聊天
• AI实时同步 -通过浏览器实时查看AI编辑笔记本电脑的情况。编辑AI时自动锁定笔记本电脑
• 数据目录词汇表现有逻辑 -通过2层结构（索引+详细信息）的MCP工具，AI在有效参照业务知识的同时执行分析

体系结构

详细的体系结构图是 项目全貌 来修改标记元素的显示属性。

组件

｜名称｜概要｜端口｜ |------|------|--------| 基于JupyterLab的分析执行环境 ｜jpyter-mcp｜用于Jupyter操作的MCP服务器｜3001｜ 实时同步JupyterLab扩展（附带于jupyter-server） 数据目录词汇表逻辑管理API 目录词汇表逻辑引用MCP服务器

安装，安装

必要条件

• Docker&Docker编写
• Node.js 20+
• 紫外线 0.4+（Python 依存管理）

1.克隆存储库

git clone https://github.com/shinichiro-homma/ai-data-analysis-platform.git
cd ai-data-analysis-platform

2.初次设置

bash scripts/bootstrap.sh

同步Python依赖关系（uv sync）・git设定・.env 的明细栏样式中定义的设置。 如果未安装uv，脚本将引导您完成安装过程。 .env 复制后 POSTGRES_PASSWORD / JUPYTER_TOKEN 将条目添加到文档注册表。

3.启动服务

首次启动时通过数据环境切换脚本启动。批量完成PostgreSQL的卷初始化、启动待机、CSV数据加载：

scripts/switch-env.sh sample

以下服务将启动：

｜服务｜URL｜说明｜ |---------|-----|------| 分析对象数据库（初始加载CSV数据） | jupyter-server | http://localhost:8888在浏览器中访问 | document-server | http://localhost:3002目录词汇表逻辑API

JupyterLab在浏览器中 http://localhost:8888?token= 中所述修改相应参数的值。

docker-compose up -d 不直接使用的理由：原始 docker-compose up -d 只进行到表制作，数据装载不跑（装载从主机侧Python scripts/lib/common.sh:run_load_data 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。第一次一定 scripts/switch-env.sh sample 来修改标记元素的显示属性。production 切换到环境时 production 中所述修改相应参数的值。如果只是停止或重新启动已启动的服务 docker compose stop / docker compose start 也没关系。

4.MCP服务器构建

由于MCP服务器（jupyter-mcp，document-mcp）作为本地进程从Claude Desktop启动，因此不包含在docker-compose中。我会事先构建好的。

# jupyter-mcp
cd jupyter-mcp && npm install && cd ..
scripts/rebuild-mcp.sh jupyter-mcp

# document-mcp
cd document-mcp && npm install && cd ..
scripts/rebuild-mcp.sh document-mcp

5.Claude Desktop的连接设置

Claude Desktop的配置文件 claude_desktop_config.json （Claude Desktop菜单→ Settings → Developer → Edit Config）。配置文件的路径因操作系统而异：

操作系统路径 |----|------| |macOS| ~/Library/Application Support/Claude/claude_desktop_config.json | |Windows/WSL| %LOCALAPPDATA%\Packages\Claude_ \LocalCache\Roaming\Claude\claude_desktop_config.json |

Windows版Claude Desktop作为MSIX软件包分发，所以config文件是 %APPDATA%\Claude\ 而不是 `%LOCALAPPDATA%\Packages\Claude_

\LocalCache\Roaming\Claude\ 被配置在属下。 在实际环境中 %LOCALAPPDATA%\Packages\ 下辖 Claude_* 中所述修改相应参数的值。如果你迷路了，请在Claude Desktop菜单上 Settings → Developer → Edit Config` 打开正确的文件。

mcpServers 中添加以下条目：

{
  "mcpServers": {
    "jupyter-mcp": {
      "command": "node",
      "args": ["/jupyter-mcp/dist/index.js"],
      "env": {
        "JUPYTER_SERVER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": ""
      }
    },
    "document-mcp": {
      "command": "node",
      "args": ["/document-mcp/dist/index.js"],
      "env": {
        "DOCUMENT_SERVER_URL": "http://localhost:3002",
        "DOCUMENT_SERVER_TOKEN": ""
      }
    }
  }
}

替换点：

• ` —项目的绝对路径（在下面的“WSL情况”部分中

` ）

• ` / —项目正下方 .env` 的同名变量完全一致（不一致的话是401）

对于WSL：Claude Desktop为Windows进程，Linux路径和Linux侧 node 中所述修改相应参数的值。wsl.exe 进行动态观察时的轴心点node 的绝对路径（理由如下）。

预先在WSL上执行以下操作，以控制节点和项目的绝对路径：

which node                 # → （例: /home//.nvm/versions/node/v24.14.1/bin/node）
pwd                        # プロジェクトルートで実行 → 

控制值为 ` / 中所述修改相应参数的值。**env 除…之外 WSLENV` 必记**这是重点（原因如下）：

{
  "mcpServers": {
    "jupyter-mcp": {
      "command": "wsl.exe",
      "args": [
        "",
        "
/jupyter-mcp/dist/index.js"
      ],
      "env": {
        "JUPYTER_SERVER_URL": "http://localhost:8888",
        "JUPYTER_TOKEN": "",
        "WSLENV": "JUPYTER_SERVER_URL:JUPYTER_TOKEN"
      }
    },
    "document-mcp": {
      "command": "wsl.exe",
      "args": [
        "",
        "
/document-mcp/dist/index.js"
      ],
      "env": {
        "DOCUMENT_SERVER_URL": "http://localhost:3002",
        "DOCUMENT_SERVER_TOKEN": "",
        "WSLENV": "DOCUMENT_SERVER_URL:DOCUMENT_SERVER_TOKEN"
      }
    }
  }
}

为什么 node 的绝对路径：在nvm中安装的node是 ~/.bashrc 中所述修改相应参数的值。wsl.exe node ... 是非对话壳 .bashrc 不读wsl.exe bash -lc "node ..." 但是登录壳 .bash_profile / .profile 因为只看，所以都 node: command not found 的下界。确实要动的话 which node 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。 更新节点后重新设置：在nvm中提高node版本的话，路径的 v 部分会改变。本config的 ` 中所述修改相应参数的值。 **为什么 WSLENV 是否需要**: wsl.exe 是Claude Desktop env 中传递的Windows侧环境变量，默认情况下不会传递到Linux侧的子进程。将要传输的变量名用冒号分隔 WSLENV 中描述的场景，使用以下步骤创建明细表，以便在概念设计中分析体量的体积。WSLENV 忘记的话 DOCUMENT_SERVER_TOKEN が未設定 和jupyter侧的 HTTP 403` 的症状。

保存后，在Claude Desktop完全结束（macOS:Cmd+Q/Windows：从任务托盘结束）后重新启动，锤子图标上显示两个服务器的工具就成功了。

刀具列表

jupyter-mcp（分析実行制御）

工具概述 |--------|------| | workspace_create 创建工作区 | workspace_list 工作区列表 | workspace_update 工作区更新 | workspace_summarize 获取验证报告模板 | session_create 创建会话 | session_list 会话列表 | session_connect ｜现有会话连接｜ | session_delete 会话结束 | execute_code 执行Python代码 | get_variables | 変数一覧取得 | | get_dataframe_info | DataFrame情报取得| | notebook_create 创建笔记本电脑 | notebook_add_cell 添加单元格 | notebook_list_cells 获取单元格列表 | notebook_edit_cell 编辑单元格 | notebook_delete_cell 删除单元格 | notebook_execute_cell 重新运行单元格 | notebook_reorder_cell 单元格排序 | notebook_execute_batch ｜批量执行单元格｜ | notebook_merge_cells 单元格联接 | notebook_split_cell 拆分单元格 | notebook_change_cell_type 更改单元格类型 | notebook_copy_cell 单元格复制 | notebook_clear_outputs 输出清除 | kernel_restart 重新启动内核 | file_list 获取文件列表 | file_read 文件读取 | data_preview 数据预览 | execute_sql | SQL実行・结果确认| | export_sql SQL数据导出 | get_image | 画像取得 |

了解更多信息 文档/需求/jupyter-mcp.md 来修改标记元素的显示属性。

目录词汇表逻辑参考

工具概述 |--------|------| | get_table_index 获取表索引 | get_table_detail 获取表详细信息 | get_term_index 获取术语索引 | get_term_detail |用语详细取得| | get_logic_index 获取逻辑索引 | get_logic_detail 获取逻辑元信息 | get_logic_code 获取逻辑代码

了解更多信息 文档/要求/文档-mcp.md 来修改标记元素的显示属性。

用法

基本流程

1. 创建工作区 -AI workspace_create 确保专用工作空间
2. 创建会话 - session_create 在中启动Python内核
3. 数据目录参考 - get_table_index → get_table_detail 了解表结构
4. 分析実行 - execute_code 数据获取、加工、可视化
5. 结果确认 -AI解释并回答结果。图表在浏览器的JupyterLab中确认

在浏览器中实时确认

在浏览器中打开JupyterLab的状态下，委托AI进行分析，会实时反映AI的操作（添加单元格、执行代码、显示结果）。在AI编辑过程中，笔记本电脑会自动锁定，完成后用户可以自由编辑。

系统提示模板

为本平台提供系统提示模板 system-prompt-templates/ 缺少支持的问题。请粘贴到Claude Desktop的项目说明（Project Instructions）或API使用时的system提示符上使用。

文件/语言 |---------|------| | analysis-policy.md |英语| | analysis-policy.ja.md |日本语|

模板中包含的主要策略：

• 计划-执行一步-报告-等待 的原则（无计划不连锁工具）
• 工具调用顺序（workspace_create → session_create → notebook_create → 分析）
• 数据准备阶段（必须在SQL创建前确认术语目录表和现有逻辑）
• export_sql / execute_sql / execute_code 区分使用（原始数据取得vs.内容确认vs.统计・可视化）
• 外部文件Unicode规范化Excel读取陷阱
• 内存管理（执行各步骤前的检查和超过80%时的处理）

使用是任意的，但如果想让AI遵循一致的分析步骤，建议适用。您可以添加和自定义特定于项目的规则。

文档

文档｜内容｜ |-------------|------| | 项目全貌 架构、用例流、数据流 | 文档配置映射 文件列表与角色、更新的依赖关系 | API仕様 REST API的详细规格

要件定义

• jupyter服务器
• jupyter mcp
• 同步实验室
• 文档服务器
• 文件mcp

开発

分支模型

main (公開・リリース済み)
 └── dev (統合・検証用)
      └── feature/xxx ← dev から切る

• 日常的开发 dev 分支
• main 的反映 scripts/promote-to-main.sh 创建宣传
• 开发计划、进度管理等dev-only文档 dev 仅存在于分支中

运行测试

# jupyter-mcp のテスト
scripts/test.sh jupyter-mcp

# document-mcp のテスト
scripts/test.sh document-mcp

# document-server のテスト
scripts/test.sh document-server

# E2Eテスト（docker-compose が起動している状態で）
scripts/test.sh --integration

# コード変更後はリビルド付きで実行
scripts/test.sh --rebuild jupyter-mcp

个别开発

# MCPサーバーの開発（ホットリロード）
cd jupyter-mcp && npm run dev
cd document-mcp && npm run dev

# document-server の開発
cd document-server && uvicorn src.main:app --reload --port 3002

浏览器操作UI验证

许可证

麻省理工学院