mcp-server-one

chiarorosa/mcp-server-one

3.2

If you are the rightful owner of mcp-server-one and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MCP Server One is a Model Context Protocol server that integrates multiple public APIs into a single standardized interface, providing tools and resources for interacting with diverse data sources.

Tools
10
Resources
0
Prompts
0

MCP Server One

GitHub Python UV

Um servidor Model Context Protocol (MCP) que fornece acesso a várias APIs públicas através de uma interface padronizada. Este servidor demonstra como integrar múltiplas APIs externas em um único servidor MCP, oferecendo recursos, ferramentas e prompts para interação com dados de diferentes fontes.

🚀 Características

APIs Integradas

  1. JSONPlaceholder - API fake para desenvolvimento e testes

    • Posts, usuários, comentários e todos
    • Operações CRUD simuladas

  2. Cat Facts API - Fatos interessantes sobre gatos

    • Fatos aleatórios e coleções de fatos

  3. Official Joke API - Piadas organizadas por categoria

    • Piadas aleatórias e por tipo

  4. QR code API - Crie QR codes com base em um texto

    • Gere uma imagem png QR code de um texto

Funcionalidades MCP

  • Resources: Acesso a metadados e informações das APIs
  • Tools: Execução de operações específicas das APIs
  • Prompts: Templates para análise e inspiração
  • Logging: Sistema de logs detalhado
  • Context Management: Gerenciamento de contexto com ciclo de vida

📋 Requisitos

  • Python 3.11+
  • UV (gerenciador de pacotes Python)
  • Conexão à internet para APIs externas

🛠️ Instalação

Instalação Rápida

# 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

Instalação Detalhada

1. Clonar o repositório

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

2. Instalar dependências com UV

# Instalar dependências principais
uv sync

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

3. Instalar o pacote em modo de desenvolvimento

uv pip install -e .

Instalação com Makefile (Alternativa)

O projeto inclui um Makefile que facilita a execução dos comandos mais comuns:

# 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

Comandos principais:

  • make install - Equivale a uv sync
  • make run - Executa o servidor usando run_server.py
  • make test - Executa todos os testes
  • make format - Formata o código com black e isort
  • make lint - Executa verificações de tipo e linting

Fluxo de trabalho completo com 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

🎯 Uso

Executar o servidor

Modo Standard I/O (padrão)
uv run mcp-server-one
# ou
uv run python -m mcp_server_one.main
Modo Server-Sent Events (SSE)
uv run mcp-server-one --transport sse --port 8000
Modo Streamable HTTP
uv run mcp-server-one --transport streamable-http --port 8000
Modo de desenvolvimento
uv run mcp dev src/mcp_server_one/server.py

Testar com MCP Inspector

uv run mcp dev src/mcp_server_one/server.py

Instalar no Claude Desktop

Método 1: Configuração Automática (Mais Fácil)

Use o script de configuração incluído no projeto:

uv run python configure_claude.py

Este script irá:

  • Detectar automaticamente o sistema operacional
  • Localizar o arquivo de configuração do Claude Desktop
  • Adicionar/atualizar a configuração do MCP Server One
  • Fornecer instruções para os próximos passos
Método 2: Instalação via CLI do MCP

Pré-requisitos:

  • Certifique-se de que o pacote MCP está instalado com o extra CLI:
uv add 'mcp[cli]'
uv sync

Instalação:

uv run mcp install src/mcp_server_one/server.py --name "MCP Server One"
Método 3: Instalação Manual

Se o comando automático não funcionar (erro "Claude app not found"), configure manualmente:

  1. Localize o arquivo de configuração do Claude Desktop:

    • Windows: %APPDATA%\Claude\claude_desktop_config.json
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Linux: ~/.config/Claude/claude_desktop_config.json

  2. Adicione a configuração do servidor:

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "CAMINHO_COMPLETO_DO_PROJETO",
        "mcp-server-one"
      ],
      "env": {}
    }
  }
}
  1. Substitua CAMINHO_COMPLETO_DO_PROJETO pelo caminho absoluto do seu projeto.
Método 4: Usando Python direto

Alternativa usando Python diretamente:

{
  "mcpServers": {
    "mcp-server-one": {
      "command": "python",
      "args": ["-m", "mcp_server_one.main"],
      "cwd": "CAMINHO_COMPLETO_DO_PROJETO",
      "env": {}
    }
  }
}
Exemplos de Configuração por Sistema Operacional
Windows
{
  "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 (Windows Subsystem for Linux)
{
  "mcpServers": {
    "mcp-server-one": {
      "command": "wsl",
      "args": [
        "uv",
        "run",
        "--directory",
        "/mnt/d/Code/mcp-server-one",
        "mcp-server-one"
      ],
      "env": {}
    }
  }
}

Dica: Após editar o arquivo de configuração, reinicie o Claude Desktop para aplicar as mudanças.

📚 Recursos Disponíveis

Resources (Recursos)

  • posts://all - Informações sobre todos os posts
  • posts://{post_id} - Informações sobre um post específico
  • users://all - Informações sobre todos os usuários
  • api://status - Status e documentação das APIs disponíveis

Tools (Ferramentas)

JSONPlaceholder
  • get_posts(limit?) - Busca posts (com limite opcional)
  • get_post_by_id(post_id) - Busca post específico
  • get_users() - Busca todos os usuários
  • get_user_by_id(user_id) - Busca usuário específico
  • get_todos(user_id?) - Busca todos (opcionalmente de um usuário)
  • create_post(title, body, user_id) - Cria post (simulado)
Cat Facts
  • get_cat_fact() - Fato aleatório sobre gatos
  • get_multiple_cat_facts(limit=5) - Múltiplos fatos sobre gatos
Jokes
  • get_random_joke() - Piada aleatória
  • get_jokes_by_type(type) - Piadas por tipo (programming, general, etc.)

Prompts (Templates)

  • analyze_post(post_id) - Análise detalhada de um post
  • user_profile_analysis(user_id) - Análise de perfil de usuário
  • daily_inspiration() - Mensagem de inspiração diária

🔧 Configuração

Variáveis de ambiente

O servidor não requer configuração específica, mas você pode personalizar:

export MCP_SERVER_PORT=8000
export MCP_LOG_LEVEL=INFO

🧪 Testes

Executar testes

Usando UV diretamente:

# 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

Usando Makefile (mais fácil):

# Todos os testes
make test

# Testar conectividade com APIs externas
make test-apis

Testes de integração

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

📊 Desenvolvimento

Estrutura do projeto

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
Arquivos Principais
  • src/mcp_server_one/main.py: Ponto de entrada da aplicação
  • src/mcp_server_one/server.py: Implementação do servidor MCP
  • src/mcp_server_one/api_client.py: Gerenciador das APIs externas
  • configure_claude.py: Script para configuração automática do Claude Desktop
  • pyproject.toml: Configuração do projeto, dependências e scripts

Linting e formatação

Usando UV diretamente:

# 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/

Usando Makefile (mais fácil):

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

# Executar linting (mypy + flake8)
make lint

# Executar testes
make test

# Limpar arquivos temporários
make clean

Adicionar nova API

  1. Adicione a classe da API em api_client.py
  2. Registre no APIManager
  3. Adicione tools no server.py
  4. Adicione testes em test_api_client.py

🔍 Exemplos de Uso

1. Buscar posts

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

2. Análise de usuário

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

3. Inspiração diária

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

🤝 Contribuição

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/nova-feature)
  3. Commit suas mudanças (git commit -am 'Adiciona nova feature')
  4. Push para a branch (git push origin feature/nova-feature)
  5. Crie um Pull Request

Diretrizes de contribuição

  • Mantenha o código limpo e bem documentado
  • Adicione testes para novas funcionalidades
  • Siga o estilo de código existente
  • Atualize a documentação quando necessário

📝 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.

🆘 Suporte

Problemas comuns

  1. Erro de importação do MCP: Certifique-se de que o pacote mcp está instalado
  2. APIs não respondem: Verifique sua conexão com a internet
  3. Porta em uso: Mude a porta com --port
  4. Erro "typer is required. Install with 'pip install mcp[cli]'": Execute uv add 'mcp[cli]' e depois uv sync
  5. Erro "Claude app not found": Use o script de configuração automática (uv run python configure_claude.py) ou configure manualmente o arquivo de configuração do Claude Desktop

Nota: Se você encontrar problemas com o ambiente virtual, execute:

rm -rf .venv && uv sync

Logs e debugging

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

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

Contato

🤝 Contribuindo

Contribuições são bem-vindas! Por favor, veja para detalhes sobre como contribuir.

  1. Fork o projeto
  2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
  3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
  4. Push para a branch (git push origin feature/AmazingFeature)
  5. Abra um Pull Request

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo para detalhes.

🎉 Agradecimentos

Feito com ❤️ usando Model Context Protocol e UV