点击展开更新日志

2025

07-28

  1. 环境准备
  2. MCP Server

nexttime

会有些什么呢(❁´◡`❁)

源起

起因是突然想在本地搭建自己的知识库，然后顺便做一个自动化的签到流程，最初的想法是利用 playwrigth 可视化把过程记录下来，但是发现效果并不好，于是决定还是自己写，然后套上 MCP（当当，点题！），已经在另一台设备上完全跑通了，调用也没有问题。问题是重装系统时忘记备份了（真是服了。。），干脆重新在主机上重新搞一遍，并记录。

环境准备

主机环境

  • 操作系统：Win11 24H2 专业版
  • IDE：PyCharm
  • Python：3.13

Python

采用 Python 开发（因为最简单）。安装过程略过，建议选择最新版，本文所用版本为 3.13 。可以选择安装 miniforge 进行环境管理【强烈推荐】

miniforge

安装

如果是 Windows 安装，应该会默认添加环境变量，没有就手动加一下：将 C:\Users\myusername\miniforge3\condabin 添加到环境变量 PATH 。

打开终端初始化：

1
conda init

配置

如果不希望虚拟环境安装到默认的 C盘，觉着官方通道下载太慢，可以选择修改配置文件：

  1. 先执行 conda config --list > .condarc 创建默认配置文件；

    之所以这么做是因为直接创建空文件报了错误，后面发现是编码要使用GBK，你问为什么不是 UTF-8，许是 Windows 终端不认识吧。

  2. 参考配置：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    channels:
      - defaults
    show_channel_urls: true
    default_channels:
      - https://mirrors.ustc.edu.cn/anaconda/pkgs/main
      - https://mirrors.ustc.edu.cn/anaconda/pkgs/r
      - https://mirrors.ustc.edu.cn/anaconda/pkgs/msys2
    custom_channels:
      conda-forge: https://mirrors.ustc.edu.cn/anaconda/cloud
      bioconda: https://mirrors.ustc.edu.cn/anaconda/cloud
    envs_dirs:
      - F:\envs\conda\envs
    pkgs_dirs:
      - F:\envs\conda\pkgs
    1. 更换仓库源为中科大Anaconda源
    2. 更改虚拟环境和包默认安装位置

    ❓为什么不用清华源：你可以试试，我在安装这天（20250727）使用清华源报403错误，原因未知。

  3. 验证：

    1
    conda -V

  4. 常用命令

    只列几个经常用的，想了解更多可以参考conda 官方文档

    命令 说明
    conda activate <ENV_NAME> 激活环境
    conda create -n|–name <ENV_NAME> 创建环境
    conda deactivate 在已激活环境内执行，退出当前激活环境

uv

MCP 建议使用 uv 创建环境,那就用呗。

安装

安装命令：

1
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

为了保证项目一致性，建议后续包管理都用 uv，如果用 pip 到也没问题（毕竟我就是用完之后才意识到问题）。

基础使用

参考资料：UV使用教程-又一岁荣枯

创建虚拟环境(uv venv)

1
2
3
4
5
6
7
8
# 在当前目录下创建一个名为 .venv 的虚拟环境，使用系统默认的 Python 版本
uv venv

# 在当前目录下创建一个名为 my-project-env 的虚拟环境，使用指定的 Python 3.11 版本
uv venv -p python3.11 my-project-env

# 在指定路径创建一个名为 custom-env 的虚拟环境，使用 Python 3.10
uv venv -p python3.10 /path/to/my/project/custom-env

安装包(uv pip install)

需要先激活虚拟环境！

这里的 pip 是 uv 本身的安装命令，不是 python 的 pip。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
# 确保你已经激活了虚拟环境 
# Windows (CMD): .\venv\Scripts\activate
# macOS/Linux (Bash/Zsh): source venv/bin/activate

# 安装 requests 包
uv pip install requests

# 安装指定版本的 Flask 包
uv pip install Flask==2.2.2

# 从 requirements.txt 文件安装所有依赖
uv pip install -r requirements.txt

# 安装开发依赖 (通常在 requirements-dev.txt 中)
uv pip install -r requirements-dev.txt -d dev

卸载包(uv pip uninstall)

需要先激活虚拟环境，然后卸载指定包。

1
2
3
4
5
6
7
# 确保你已经激活了虚拟环境

# 卸载 requests 包
uv pip uninstall requests

# 卸载多个包
uv pip uninstall Flask Werkzeug

列出已安装的包(uv pip list)

1
2
# 列出当前激活虚拟环境已安装的包及版本
uv pip list

导出依赖文件(uv pip freeze)

导出当前激活虚拟环境的依赖包到文件。

1
2
3
4
5
# 导出到默认的 requirements.txt 文件
uv pip freeze > requirements.txt

# 导出到指定的文件
uv pip freeze > my_dependencies.txt

运行工具(uv tool run)或别名(uvx)

运行由 Python 包提供的命令行工具，无需显式安装到当前虚拟环境或全局环境。uv 会自动创建一个临时的隔离环境来运行该工具。

1
2
3
4
5
6
7
8
# 运行 black 代码格式化工具
uvx black .

# 运行 flake8 代码检查工具
uv tool run flake8 my_module.py

# 运行指定版本的 pylint
uvx [email protected] my_module.py

移除虚拟环境(uv venv --remove)

1
2
3
4
5
# 删除当前目录下的名为 .venv 的虚拟环境
uv venv --remove .venv

# 删除指定路径的虚拟环境
uv venv --remove /path/to/my/project/my-project-env

初始化项目

默认已经完成了以上环境安装：

  1. 初始化项目：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    # 在当前目录下初始化名为 mcp_server 的MCP 项目目录
    uv init mcp_server
    cd mcp_server

    # 创建虚拟环境
    uv venv
    .venv\Scripts\activate

    # 安装依赖
    uv add mcp[cli] httpx

    # 添加 playwrigth：我需要使用 playwright 进行网站操作，故装之，如果不懂或不需要不用装
    # pip 清华源：https://mirrors.tuna.tsinghua.edu.cn/pypi/web/simple
    pip install playwright

    不建议使用系统自带浏览器，因为用户使用和自动化操作会冲突（我需要使用cookie保存登录状态），因此建议分开。

  2. 使用 PyCharm 等 IDE 打开项目

  3. 开始愉快的玩耍！

MCP server

  1. 一切就和常规开发一样，新建一个项目包，新建一个 Python 文件，写好你的代码

  2. 在项目根目录下 main.py，添加以下内容：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    from mcp.server.fastmcp import FastMCP
    from mcp.server.fastmcp.server import Settings


    mcp = FastMCP("web-check")
    settings = Settings()
    settings.host = "0.0.0.0" # 监听地址
    settings.port = 80        # 监听端口
    settings.streamable_http_path = "/mymcp"  # 访问路径
    mcp.settings = settings

    mcp.run(transport="streamable-http")  # 传输方式


    @mcp.tool("websites_check")
    async def myapp() -> json:
        return {"success": "True"}

  3. 启动项目，控制台输出：

    1
    2
    3
    4
    5
    6
    INFO:     Waiting for application startup.
    [07/29/25 17:11:25] INFO     StreamableHTTP      streamable_http_manager.py:110
                                session manager                                   
                                started                                           
    INFO:     Application startup complete.
    INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

  4. 打开 MCP 主机，以 Cherry Studio 为例：

    Cherry Studio 配置

    路径后缀是遵循 MCP 协议标准请求路径，默认为：

    • stdio：命令参数配置
    • sse：/sse
    • ​​Streamable-HTTP​：/mcp

    如果想要自定义，可以导入 Settings 包进行修改，几点说明：

    1. mcp.run 中的 mount_path 也可以默认请求路径，但仅对 sse 有效
    2. 如果需要局域网其它设备访问，监听地址可以设置为本机局域网地址(192.168.x.x)，设置成 0.0.0.0 也可以，但不建议，安全性差(不过在局域网也无关紧要，看个人)

不常见问题

同步异步处理

因功能函数使用了同步，MCP 工具函数声明用的是异步，因此启动会存在问题：

  1. 修改工具类为异步：我是做的站点签到，担心异步存在问题因此不采用
  2. 修改MCP工具类调用方式，如下(仅保留核心配置)
1
2
3
4
5
6
7
8
9
10
11
12
# 工具类
from playwright.sync_api import sync_playwright
def checkin():
  with sync_playwright() as p:
    pass
    

# MCP 入口类
import asyncio
@mcp.tool("webcheck")
async def web_check() -> json:
  return await asyncio.to_thread(checkin())