使用说明

MCP服务器一

模型上下文协议（MCP）服务器，通过标准化接口提供对多个公共 API 的访问。本服务器演示了如何将多个外部 API 集成到单个 MCP 服务器中，为不同来源的数据提供功能、工具和提示。

🚀 特征

API集成

JSON占位符 用于开发和测试的假API
- 文章，用户，评论和所有
- 模拟 CRUD 操作
Cat事实API 关于猫的有趣事实
- 随机事实和事实集合
API官方笑话 按类别组织的笑话
- 随机笑话和类型
二维码API - 基于文本创建QR码
- 从文本生成png图像QR码

MCP功能

资源访问元数据和 API 信息
工具执行特定的 API 操作
鼓励分析和灵感模板
日志记录详细的系统日志
上下文管理生命周期上下文管理

📋 要求

Python 3.11+
UV （Python 软件包管理器）
外部 API 的互联网连接

🛠️ 安装

快速安装

# Clone o repositório
git clone https://github.com/chiarorosa/mcp-server-one.git
cd mcp-server-one

# Instale as dependências
uv sync

# Execute o servidor
uv run mcp-server-one

安装详情

1. 克隆仓库

git clone https://github.com/chiarorosa/mcp-server-one.git
cd mcp-server-one

2. 安装紫外线依赖

# Instalar dependências principais
uv sync

# Instalar dependências de desenvolvimento
uv sync --dev

3. 在开发模式下安装软件包

uv pip install -e .

使用 Makefile 安装（可选）

该项目包含一个Makefile，可以轻松执行最常见的命令：

# Ver todos os comandos disponíveis
make help

# Instalar dependências
make install

# Executar o servidor
make run

# Executar testes
make test

# Testar conectividade com APIs
make test-apis

# Formatar código
make format

# Executar linting
make lint

# Limpar arquivos temporários
make clean

主要命令：

make install -等价物a uv sync
make run - 使用运行服务器 run_server.py
make test 运行所有测试
make format 用black和isort格式化代码
make lint - 执行类型和linting检查

完整的 Makefile 工作流程：

# 1. Instalar dependências
make install

# 2. Executar testes para verificar se tudo está funcionando
make test

# 3. Testar conectividade com APIs externas
make test-apis

# 4. Executar o servidor
make run

🎯 谎言

运行服务器

标准 I/O 模式

uv run mcp-server-one
# ou
uv run python -m mcp_server_one.main

Modo服务器发送事件（SSE）

uv run mcp-server-one --transport sse --port 8000

HTTP流模式

uv run mcp-server-one --transport streamable-http --port 8000

开发模式

uv run mcp dev src/mcp_server_one/server.py

使用 MCP Inspector 测试

uv run mcp dev src/mcp_server_one/server.py

不稳定的无克劳德桌面

方法1：自动设置（更简单）

使用工程中包含的配置脚本：

uv run python configure_claude.py

该脚本将：

自动检测操作系统
查找 Claude Desktop 配置文件
添加/更新 MCP Server One 配置
为下一步提供说明

方法 2：通过 MCP CLI 安装

先决条件：

确保 MCP 套件安装了额外的 CLI：

uv add 'mcp[cli]'
uv sync

安装：

uv run mcp install src/mcp_server_one/server.py --name "MCP Server One"

方法3：手动安装

如果自动命令不起作用（“Claude app not found”错误），请手动配置：

查找 Claude Desktop 配置文件：
- 视窗: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
添加服务器配置：

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "CAMINHO_COMPLETO_DO_PROJETO",
        "mcp-server-one"
      ],
      "env": {}
    }
  }
}

替换 CAMINHO_COMPLETO_DO_PROJETO 你的项目的绝对路径。

方法4：直接使用Python

直接使用 Python 的替代方案：

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "python",
      "args": ["-m", "mcp_server_one.main"],
      "cwd": "CAMINHO_COMPLETO_DO_PROJETO",
      "env": {}
    }
  }
}

按操作系统配置示例

视窗

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "d:\\Code\\mcp-server-one",
        "mcp-server-one"
      ],
      "env": {}
    }
  }
}

macOS/Linux

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/caminho/para/mcp-server-one",
        "mcp-server-one"
      ],
      "env": {}
    }
  }
}

WSL（Linux的Windows子系统）

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "wsl",
      "args": [
        "uv",
        "run",
        "--directory",
        "/mnt/d/Code/mcp-server-one",
        "mcp-server-one"
      ],
      "env": {}
    }
  }
}

说：编辑配置文件后，重新启动 Claude Desktop 以应用更改。

📚 可用资源

资源（资源）

posts://all 关于所有帖子的信息
posts://{post_id} 关于特定文章的信息
users://all 关于所有用户的信息
api://status - 可用API的状态和文档

工具（Tools）

JSON占位符

get_posts(limit?) - 搜索职位（可选限制）
get_post_by_id(post_id) 搜索特定的帖子
get_users() 搜索所有用户
get_user_by_id(user_id) 搜索特定用户
get_todos(user_id?) 全部搜索（可选一个用户）
create_post(title, body, user_id) - 创建文章（模拟）

猫的事实

get_cat_fact() 关于猫的随机事实
get_multiple_cat_facts(limit=5) 关于猫的许多事实

笑话

get_random_joke() - 随机玩笑
get_jokes_by_type(type) - 按类型的笑话（编程，一般等）

提示（模板）

analyze_post(post_id) 一篇文章的详细分析
user_profile_analysis(user_id) - 用户配置文件分析
daily_inspiration() 每日灵感讯息

🔧 配置

环境变量

服务器不需要特定的配置，但您可以自定义：

export MCP_SERVER_PORT=8000
export MCP_LOG_LEVEL=INFO

🧪 测试

运行测试

直接使用UV：

# Todos os testes
uv run pytest

# Testes com cobertura
uv run pytest --cov=mcp_server_one

# Testes específicos
uv run pytest tests/test_api_client.py

# Testes em modo verbose
uv run pytest -v

使用 Makefile（更简单）：

# Todos os testes
make test

# Testar conectividade com APIs externas
make test-apis

集成测试

# Testar APIs reais (requer internet)
uv run pytest tests/test_integration.py
# ou
make test-apis

📊 开发

项目结构

mcp-server-one/
├── .git/                           # Controle de versão Git
├── .gitignore                      # Arquivos ignorados pelo Git
├── .venv/                          # Ambiente virtual Python
├── claude_desktop_config.md        # Documentação de configuração do Claude
├── configure_claude.py             # Script de configuração automática do Claude
├── CONTRIBUTING.md                 # Guia de contribuição
├── DEVELOPMENT.md                  # Guia de desenvolvimento
├── LICENSE                         # Licença MIT
├── Makefile                        # Comandos de automação
├── pyproject.toml                  # Configuração do projeto e dependências
├── README.md                       # Documentação principal
├── run_server.py                   # Script para execução do servidor
├── standalone_server.py            # Servidor standalone
├── test_apis.py                    # Testes das APIs
├── test_import.py                  # Testes de importação
├── uv.lock                         # Lock file das dependências
├── src/
│   └── mcp_server_one/
│       ├── __init__.py             # Inicialização do pacote
│       ├── api_client.py           # Cliente das APIs externas
│       ├── main.py                 # Ponto de entrada principal
│       └── server.py               # Servidor MCP principal
├── tests/
│   ├── __init__.py                 # Inicialização dos testes
│   └── test_api_client.py          # Testes unitários do cliente API
└── examples/
    ├── simple_demo.py              # Demonstração simples
    └── test_client.py              # Cliente de teste

主要档案

src/mcp_server_one/main.py：应用入口点
**src/mcp_server_one/server.py**MCP 服务器部署
**src/mcp_server_one/api_client.py**外部 API 管理器
**configure_claude.py**自动配置 Claude Desktop 的脚本
**pyproject.toml**项目配置、依赖关系和脚本

Linting 和格式

直接使用UV：

# Formatação com black
uv run black src/ tests/

# Ordenação de imports
uv run isort src/ tests/

# Verificação de tipos
uv run mypy src/

# Linting
uv run flake8 src/ tests/

使用 Makefile（更简单）：

# Formatar código (black + isort)
make format

# Executar linting (mypy + flake8)
make lint

# Executar testes
make test

# Limpar arquivos temporários
make clean

添加新 API

将API类添加到 api_client.py
注册号 APIManager
添加工具 server.py
添加测试到 test_api_client.py

🔍 使用范例

1.公共汽车站

# Através do cliente MCP
result = await session.call_tool("get_posts", {"limit": 5})

2. 用户分析

# Usar o prompt de análise
prompt = await session.get_prompt("user_profile_analysis", {"user_id": 1})

3. 日常灵感

# Usar o prompt de inspiração
prompt = await session.get_prompt("daily_inspiration", {})

🤝 贡献

分叉工程
为您的功能创建一个分支（git checkout -b feature/nova-feature)
提交您的更改（git commit -am 'Adiciona nova feature')
推动一个分支(git push origin feature/nova-feature)
Crie-um Pull请求

贡献准则

保持代码清洁和记录良好
添加新功能测试
生存估计信号
必要时更新文档

📝 许可证

这个项目是MIT许可的。查看文件 LICENSE 为了细节。

🆘 支持

常见问题

MCP 导入错误请确保包装 mcp 已安装
API没有响应检查您的互联网连接
正在使用的门: 将门更改为 --port
Erro“需要typer。使用'pip Install mcp[cli]进行安装”：执行 uv add 'mcp[cli]' 然后 uv sync
Erro“未找到Claude应用程序”: 使用自动配置脚本（uv run python configure_claude.py或手动配置 Claude Desktop 配置文件

注：如果您在虚拟环境中遇到问题，请执行：

rm -rf .venv && uv sync

记录调试

# Modo verbose
uv run mcp-server-one --verbose

# Logs detalhados
uv run mcp dev src/mcp_server_one/server.py --log-level DEBUG

联系方式

问题： GitHub问题
讨论： GitHub讨论

🤝 贡献

欢迎捐款！请看贡献.md 详细了解如何贡献。

分叉工程
为您的功能创建一个分支（git checkout -b feature/AmazingFeature)
提交您的更改（git commit -m 'Add some AmazingFeature')
推动一个分支(git push origin feature/AmazingFeature)
打开 Pull Request

📄 许可证

这个项目是根据麻省理工学院许可证授权的 - 查看文件许可证为了细节。

🎉 致谢

模型上下文协议按规格
JSON占位符通过 API 测试
Cat事实API 有趣的事实
API官方笑话因为笑话
二维码API 通过生成QR码

由❤️ 使用 Model Context Protocol 和 UV

使用说明

MCP服务器一

🚀 特征

API集成

MCP功能

📋 要求

🛠️ 安装

快速安装

安装详情

1. 克隆仓库

2. 安装紫外线依赖

3. 在开发模式下安装软件包

使用 Makefile 安装 （可选）

🎯 谎言

运行服务器

标准 I/O 模式

Modo服务器发送事件（SSE）

HTTP流模式

开发模式

使用 MCP Inspector 测试

不稳定的无克劳德桌面

方法1：自动设置（更简单）

方法 2：通过 MCP CLI 安装

方法3：手动安装

方法4：直接使用Python

按操作系统配置示例

视窗

macOS/Linux

WSL（Linux的Windows子系统）

📚 可用资源

资源（资源）

工具（Tools）

JSON占位符

猫的事实

笑话

提示（模板）

🔧 配置

环境变量

🧪 测试

运行测试

集成测试

📊 开发

项目结构

主要档案

Linting 和格式

添加新 API

🔍 使用范例

1.公共汽车站

2. 用户分析

3. 日常灵感

🤝 贡献

贡献准则

📝 许可证

🆘 支持

常见问题

记录调试

联系方式

🤝 贡献

📄 许可证

🎉 致谢

相关 MCP

Figma MCP服务器

实时网络搜索服务

Markdown转换服务

MCP 协议测试服务器

图像生成服务

滴滴出行MCP服务

使用 Makefile 安装（可选）