CipherTrust Manager

Servidor MCP do CipherTrust Manager

Este projeto implementa um servidor MCP (Model Context Protocol) do CipherTrust desenvolvido de forma independente, que permite que assistentes de IA como Claude ou Cursor interajam com os recursos do CipherTrust Manager usando a CLI ksctl.

Sumário

• Aviso Importante
• Recursos
• Pré-requisitos
• Instalação
• Configuração
• Uso
• Testes
• Integração com Assistentes de IA
• Variáveis de Ambiente
• Solução de Problemas
• Estrutura do Projeto
• Contribuição
• Avisos Legais
• Licença

Aviso Importante

Este é um projeto independente e de código aberto. Por favor, observe:

• ⚠️ Não é oficialmente suportado pela Thales
• ✅ Usa APIs públicas e interfaces documentadas
• 🔧 Mantido de forma independente
• 📝 Use por sua conta e risco - teste minuciosamente em seu ambiente
• 💼 Sem garantias - consulte a licença para os termos completos

Para suporte oficial do CipherTrust Manager, entre em contato diretamente com a Thales.

Recursos

O servidor MCP expõe um conjunto de ferramentas e endpoints para que clientes (como Claude Desktop e Cursor) interajam com os recursos do CipherTrust. As operações suportadas incluem:

• Gerenciamento de chaves
• Gerenciamento de clientes CTE
• Gerenciamento de usuários
• Gerenciamento de conexões
• E muito mais

Benefícios:

• Interface unificada para assistentes de IA interagirem com o CipherTrust Manager
• Suporte para gerenciamento de chaves, gerenciamento de conexões, gerenciamento de clientes CTE e muito mais
• Comunicação JSON-RPC via stdin/stdout
• Configurável por meio de variáveis de ambiente

Pré-requisitos

• Git
• Python 3.11 ou superior
• uv para gerenciamento de dependências
• Acesso a uma instância do CipherTrust Manager

Instalando o Git (Windows)

Se você não tiver o Git instalado no Windows, siga estes passos:

• Baixe e instale o Git para Windows: https://git-scm.com/download/win
• Ou instale via winget:

  winget install --id Git.Git -e --source winget
  

• Verifique a instalação - Abra o PowerShell e execute:

  git --version
  

  Você deve ver a versão do Git instalada.

Instalando Python e uv

Método 1: Instalação Manual

1. Baixe o Python

# Open PowerShell as Administrator (optional)
cd $env:USERPROFILE\Downloads
Invoke-WebRequest -Uri "https://www.python.org/ftp/python/3.12.4/python-3.12.4-amd64.exe" -OutFile "python-installer.exe"

2. Execute o Instalador

.\python-installer.exe /quiet InstallAllUsers=1 PrependPath=1 Include_test=0

3. Verifique a Instalação

Abra um novo terminal e execute:

python --version
pip --version

4. Instale o uv

pip install uv
uv --version

5. Clone o Repositório

git clone https://github.com/sanyambassi/ciphertrust-manager-mcp-server.git
cd ciphertrust-manager-mcp-server

6. Crie um Ambiente Virtual e Instale as Dependências

uv venv
.venv\Scripts\activate
uv pip install -e .

Método 2: Usando winget (Windows)

1. Instale o Python com winget

winget install --id Python.Python.3.12 --source winget --accept-package-agreements --accept-source-agreements

2. Feche e Reabra o PowerShell

Isso garante que o Python esteja disponível no seu PATH.

3. Verifique a Instalação

python --version
pip --version

4. Instale o uv

pip install uv
uv --version

5. Clone o Repositório

git clone https://github.com/sanyambassi/ciphertrust-manager-mcp-server.git
cd ciphertrust-manager-mcp-server

6. Crie um Ambiente Virtual e Instale as Dependências

uv venv
.venv\Scripts\activate
uv pip install -e .

Configuração

(Opcional) Copie e Edite o Arquivo de Ambiente de Exemplo

Exemplo de .env:

cp .env.example .env
# Edit .env with your CipherTrust Manager details

Você também pode definir essas variáveis como variáveis de ambiente diretamente, em vez de usar um arquivo .env.

Exemplo de conteúdo do .env:

CIPHERTRUST_URL=https://your-ciphertrust-manager.example.com
CIPHERTRUST_USER=admin
CIPHERTRUST_PASSWORD=your-password-here
CIPHERTRUST_NOSSLVERIFY=true

Uso

⚠️ Importante: Antes de começar, a variável de ambiente ou o arquivo .env deve conter uma URL válida do CipherTrust Manager.

Você tem duas maneiras principais de executar o Servidor MCP do CipherTrust:

Método 1: Execução Direta

uv run ciphertrust-mcp-server

Isso executa a função main() em ciphertrust_mcp_server/__main__.py.

Método 2: Execução como Módulo

uv run python -m ciphertrust_mcp_server.__main__

Testes

Este projeto inclui capacidades abrangentes de teste usando o Model Context Protocol Inspector e testes unitários em Python.

Teste Rápido

# Manual JSON-RPC testing (direct stdin/stdout)
uv run ciphertrust-mcp-server
# Then send JSON-RPC commands (see TESTING.md for details)

# Interactive UI testing (opens browser interface)
npx @modelcontextprotocol/inspector uv run ciphertrust-mcp-server

# Quick CLI testing
# Get tools
npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/list
# Get system information
npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name system_information --tool-arg action=get
# Get 2 keys
npx @modelcontextprotocol/inspector --cli --config tests/mcp_inspector_config.json --server ciphertrust-local --method tools/call --tool-name key_management --tool-arg action=list --tool-arg limit=2

Métodos de Teste Disponíveis

• 🔧 Teste Manual JSON-RPC: Comunicação direta via stdin/stdout para depuração e desenvolvimento
• 🖥️ Teste Interativo com Interface: Interface web visual para testes manuais e depuração
• ⚡ Teste Automatizado via CLI: Automação de linha de comando para integração CI/CD
• 🧪 Testes Unitários em Python: Testes unitários abrangentes para componentes do servidor
• 🔗 Testes de Integração: Testes de ponta a ponta com instâncias reais do CipherTrust Manager

Scripts NPM

Após criar um arquivo package.json:

npm run test:inspector:ui     # Open interactive testing interface
npm run test:inspector:cli    # Run automated CLI tests
npm run test:python          # Run Python unit tests
npm run test:full           # Run complete test suite

Guia Abrangente de Testes

📖 Para instruções detalhadas de teste, consulte TESTING.md

🔧 Para exemplos de prompts para assistentes de IA, consulte EXAMPLE_PROMPTS.md

O guia de testes cobre:

• Configuração e instalação completas
• Cenários avançados de teste

Os exemplos de prompts incluem:

• Operações de gerenciamento de chaves
• Gerenciamento de usuários e grupos
• Gerenciamento de sistema e serviços
• Gerenciamento de cluster
• Gerenciamento de licenças
• Operações CTE
• Operações criptográficas
• E mais cenários práticos

Integração com Assistentes de IA

Usando com o Cursor

1. Configure o Cursor

• Vá para Configurações > Ferramentas MCP > Adicionar MCP Personalizado
• Adicione o seguinte conteúdo no arquivo de configuração (por exemplo, mcp.json):

{
  "mcpServers": {
    "ciphertrust": {
      "command": "Path to your project folder/ciphertrust-manager-mcp-server/.venv/bin/ciphertrust-mcp-server",
      "args": [],
      "env": {
        "CIPHERTRUST_URL": "https://your-ciphertrust.example.com",
        "CIPHERTRUST_USER": "admin",
        "CIPHERTRUST_PASSWORD": "your-password-here"
      }
    }
  }
}

No Windows, use o caminho .venv\Scripts\ciphertrust-mcp-server.exe e barras invertidas duplas:

{
  "mcpServers": {
    "ciphertrust": {
      "command": "C:\\path\\to\\ciphertrust-manager-mcp-server\\.venv\\Scripts\\ciphertrust-mcp-server",
      "args": [],
      "env": {
        "CIPHERTRUST_URL": "https://your-ciphertrust.example.com",
        "CIPHERTRUST_USER": "admin",
        "CIPHERTRUST_PASSWORD": "your-password-here"
      }
    }
  }
}

2. Aplique a Configuração

Desative e reative o servidor MCP do CipherTrust no Cursor para aplicar as alterações.

Usando com o Claude Desktop

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

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

2. Adicione ou atualize a configuração do servidor MCP:

Exemplo para macOS/Linux:

{
  "mcpServers": {
    "ciphertrust": {
      "command": "/absolute/path/to/ciphertrust-manager-mcp-server/.venv/bin/ciphertrust-mcp-server",
      "env": {
        "CIPHERTRUST_URL": "https://your-ciphertrust.example.com",
        "CIPHERTRUST_USER": "admin",
        "CIPHERTRUST_PASSWORD": "your-password-here"
      }
    }
  }
}

Exemplo para Windows:

{
  "mcpServers": {
    "ciphertrust": {
      "command": "C:\\absolute\\path\\to\\ciphertrust-manager-mcp-server\\.venv\\Scripts\\ciphertrust-mcp-server",
      "env": {
        "CIPHERTRUST_URL": "https://your-ciphertrust.example.com",
        "CIPHERTRUST_USER": "admin",
        "CIPHERTRUST_PASSWORD": "your-password-here"
      }
    }
  }
}

Ajuste o caminho para corresponder ao local real do seu projeto e ambiente.

3. Reinicie o Claude Desktop

Reinicie o Claude Desktop para aplicar as alterações.

Variáveis de Ambiente

Defina estas variáveis no seu shell ou em um arquivo .env na raiz do projeto:

Nome da Variável	Descrição	Obrigatório/Padrão
CIPHERTRUST_URL	URL do CipherTrust Manager (http/https)	Obrigatório
CIPHERTRUST_USER	Nome de usuário do CipherTrust Manager	Obrigatório
CIPHERTRUST_PASSWORD	Senha do CipherTrust Manager	Obrigatório
CIPHERTRUST_NOSSLVERIFY	Desabilitar verificação SSL (true/false)	false
CIPHERTRUST_TIMEOUT	Tempo limite para solicitações ao CipherTrust (segundos)	30
CIPHERTRUST_DOMAIN	Domínio padrão do CipherTrust	root
CIPHERTRUST_AUTH_DOMAIN	Domínio de autenticação	root
KSCTL_PATH	Caminho para o binário ksctl	~/.ciphertrust-mcp/ksctl
KSCTL_CONFIG_PATH	Caminho para o arquivo de configuração ksctl	~/.ksctl/config.yaml
LOG_LEVEL	Nível de registro (DEBUG, INFO)	INFO

Exemplo de arquivo .env:

CIPHERTRUST_URL=https://your-ciphertrust.example.com
CIPHERTRUST_USER=admin
CIPHERTRUST_PASSWORD=yourpassword
CIPHERTRUST_NOSSLVERIFY=false
CIPHERTRUST_TIMEOUT=30
CIPHERTRUST_DOMAIN=root
CIPHERTRUST_AUTH_DOMAIN=root
KSCTL_PATH=
KSCTL_CONFIG_PATH=
LOG_LEVEL=INFO

Solução de Problemas

Registros de inicialização bem-sucedidos:

• O servidor foi projetado para ser executado como um subprocesso por clientes MCP (como Claude Desktop ou Cursor) e se comunica via JSON-RPC sobre stdin/stdout.
• Você verá saída de registro como no log MCP do assistente de IA:

2025-06-16 02:22:30,462 - ciphertrust_mcp_server.server - INFO - Starting ciphertrust-manager v0.1.0
2025-06-16 02:22:30,838 - ciphertrust_mcp_server.server - INFO - Successfully connected to CipherTrust Manager
2025-06-16 02:22:30,838 - ciphertrust_mcp_server.server - INFO - MCP server ready and waiting for JSON-RPC messages on stdin...

Dependências

O arquivo pyproject.toml inclui estas dependências:

• mcp>=1.0.0
• pydantic>=2.0.0
• pydantic-settings>=2.0.0
• httpx>=0.27.0
• python-dotenv>=1.0.0

Se você encontrar problemas, certifique-se de que todas as dependências estejam instaladas e atualizadas.

Estrutura do Projeto

ciphertrust-manager-mcp-server/
├── src
│   ├── ciphertrust_mcp_server/     # Main server code
├── tests/                      	# Testing configuration and unit tests
│   ├── mcp_inspector_config.json
│   ├── test_scenarios.json
│   ├── test_server.py
│   └── test_integration_simple.py
├── scripts/                    	# Testing and utility scripts
│   ├── test_with_inspector.bat
│   ├── test_with_inspector.sh
│   └── run_tests.py
├── docs/                      		# Additional documentation
│   ├── TESTING.md
│   ├── EXAMPLE_PROMPTS.md
│   └── TOOLS.md
├── README.md                   	# This file
├── pyproject.toml             		# Python dependencies
└── package.json               		# Node.js dependencies for testing

Contribuição

Contribuições são bem-vindas! Sinta-se à vontade para enviar um Pull Request. Embora este projeto tenha começado como um projeto pessoal, as contribuições ajudam a torná-lo melhor para todos.

Avisos Legais

Aviso de Marca Registrada

CipherTrust® e marcas relacionadas são propriedade do Grupo Thales e suas subsidiárias. Este projeto não é afiliado, endossado ou patrocinado pelo Grupo Thales.

Sem Garantias

Este software é fornecido "como está", sem garantia de qualquer tipo. Use por sua conta e risco.

Suporte

Este é um projeto independente. Para suporte oficial do CipherTrust Manager, entre em contato diretamente com a Thales. Para problemas com este servidor MCP não oficial, use o rastreador de problemas do GitHub.

Licença

Este projeto está licenciado sob a Licença MIT. Consulte o arquivo LICENSE para obter detalhes.

---