gugudan MCP Mock项目
这个项目 MCP结构作为练习的示例，它包括分别用Python（FastAPI）和Node.js（Express）实现的gugudan服务器和LLM（大型语言模型）集成客户端。
我们整理了整个文件夹结构、源描述、工作原理、实践方法、API示例和学习点，以便学生、开发人员和用户都能轻松地学习。
在本地安装并运行LM Studio，并编写代码向LLM发送问题，请参阅llmstudio_client.py。
______________________________________________________________________
1.完整的文件夹/文件结构
backend/
├── app/
│ ├── mcp_gugudan_server.py # Python 구구단 MCP 서버 (FastAPI)
│ ├── client.py # MCP 서버/LLM 스마트 라우팅 클라이언트
│ ├── lmstudio_client.py # LM Studio(로컬 LLM) 연동 모듈
│ └── __init__.py
├── js_mcp_gugudan_server/
│ ├── server.js # Node.js 구구단 MCP 서버 (Express)
│ ├── package.json # Node.js 의존성
│ └── README.md # JS 서버 실행법
├── requirements.txt # Python 의존성
├── .gitignore # 불필요 파일 제외
├── .python-version # Python 버전 지정
└── README.md # (최상위) 전체 프로젝트 설명______________________________________________________________________
2.源描述和体系结构流程
（1）Python MCP gugudan服务器
- mcp_gugudan_server.py
- /mcp/gugudan 作为端点计算并返回1-9段的区段 - 例如：{“query”：“告诉我3段”}→返回3段结果
（2）Node.js MCP分区服务器
- server.js
- POST与Python服务器相同 /mcp/gugudan 提供 - 基于Express，API响应格式也相同
（3）智能客户端
- 客户端.py
- 如果问题是gugudan，请先向MCP服务器提出请求，或自动回退到LLM（LM Studio） - 例如：“告诉我九段”→MCP服务器，“韩国人口是？”→LLM
- lmstudio_client.py
- 与LM Studio API通信（本地LLM答案） - LM Studio是直接在PC上运行的免费LLM服务器，提供OpenAI兼容的REST API。 - 本项目在本地启动LM Studio（http://localhost:1234/v1/chat/completions 等）旨在接收LLM响应。
（4）其他
- requirements.txt/package.json ：每种语言的依赖性
- .gitignore ：包括Python、Node.js、编辑器和OS临时文件
体系结构流程图
[사용자 질문]
↓
[client.py]
├─(구구단 관련)─→ [MCP 서버(Python/JS)]
└─(기타 질문)───→ [LLM(LM Studio)]______________________________________________________________________
3.动作和练习方法（Step by Step）
（A）练习Python MCP gugudan服务器
- 依赖性安装
pip install -r requirements.txt- 运行服务器
python -m app.mcp_gugudan_server
# 또는
uv run python -m app.mcp_gugudan_server- 客户端运行
python -m app.client（B）Node.js MCP gugudan服务器实践
- 移动目录并安装依赖性
cd js_mcp_gugudan_server
npm install- 运行服务器
npm start（C）直接测试API
curl -X POST http://localhost:8000/mcp/gugudan -H "Content-Type: application/json" -d '{"query": "3단 알려줘"}'（D）使用client.py测试功能
1.运行client.py
python -m app.client
# 또는
uv run python -m app.client2.动作示例（输出）
질문: 3단 알려줘
[MCP 서버 응답]
3 x 1 = 3
3 x 2 = 6
...
3 x 9 = 27
질문: 대한민국의 인구는 얼마야?
-> 질문내용운 제공하는 MCP서버와 관련 없음. LLM으로 답변하겠습니다.
[LLM 직접 응답]
2023년 12월 31일 기준으로, 대한민국의 인구는 약 51,814,000명입니다.
질문: 80단 알려줘
-> 질문내용운 제공하는 MCP서버와 관련 없음. LLM으로 답변하겠습니다.
[LLM 직접 응답]
80 x 1 = 80
80 x 2 = 160
...
80 x 9 = 720- MCP服务器可以处理的gugudan（1~9段）问题将直接计算并返回。
- 其他问题（常识、80段等）将自动回退到LLM（LM Studio）进行回答。
- 通过client.py可以轻松测试实际的路由/响应行为。
______________________________________________________________________
4.学习点&实战技巧
- MCP结构 ：如何根据情况智能路由多个处理组件（服务器/LLM）
- API设计 ：在Python/Node.js两种语言中进行相同的REST API设计实践
- 错误处理 ：错误请求（例如“告诉我80段”）时graceful返回错误
- 可扩展性 ：除gugudan以外的数学运算和其他AI功能也可以轻松地扩展到相同的结构
- 实战联动 ：包括curl、客户端代码等实际API使用方法
______________________________________________________________________
5.参考/其他资料
.gitignore包含Python/Node.js/编辑器/OS临时文件- LM Studio（Llama 3等）API集成示例
app/lmstudio_client.py请参见 - Node.js版本
js_mcp_gugudan_server/README.md请参见
______________________________________________________________________
【附录】LLM（LM Studio）配置和使用指南
LM工作室？
- LM工作室是可直接在PC上运行的免费大型语言模型（LLM）服务器。
- OpenAI API와 호환되는 REST API(
http://localhost:1234/v1/chat/completions等）。 - 可以下载GPT-3、Llama3等多种型号，在本地进行私有化。
在本项目中的应用
app/lmstudio_client.py将问题发送到LM Studio API，LLM将生成答案。- 客户端（client.py）自动将MCP服务器无法处理的问题（如gugudan）路由到LM Studio。
- LM Studio必须在PC上运行，默认端口为1234。
LM Studio设置示例
- LM Studio官方网站从下载并安装
- 运行LM Studio后，选择并下载所需型号（例如Llama 3）
- 启用“OpenAI Compatible API”功能（切换设置）
- 服务器启动后
http://localhost:1234/v1/chat/completions可以通过地址请求API
示例代码（app/lmstudio_client.py）
LMSTUDIO_API_URL = "http://localhost:1234/v1/chat/completions"
# ... 이하 생략 ...______________________________________________________________________
本资料旨在为首次学习MCP结构和服务器-客户机-LLM集成的学生/开发人员/用户提供实践帮助。如果有疑问或扩展想法，请随时提问！