ZIN MCP Client

Nota de arquivamento:

Primeiramente, obrigado a todos que apoiaram este projeto. Mas preciso torná-lo somente leitura e interromper desenvolvimentos futuros devido aos motivos abaixo:

• Outros Projetos: Preciso trabalhar em outros projetos que são muito mais úteis
• Limitação de Recursos: Devido a tempo e recursos limitados, não consigo adicionar mais funcionalidades nele
• Alternativas Melhores: Mesmo que eu trabalhe neste projeto e adicione muitos outros recursos, o resultado final não fará sentido, pois tais funcionalidades relacionadas ao cliente MCP já estão implementadas em outras alternativas. Então, quero gastar esse tempo em outros projetos, como Jadx AI MCP
• Objetivo Alcançado: O objetivo inicial deste projeto é criar um cliente MCP leve baseado em CLI para que eu possa testar meus servidores MCP. Adicionar mais funcionalidades apenas o tornará algo que não foi planejado para ser. Por exemplo, a atualização da interface web que implementei, mas elas estão fora de contexto, pois já existem alternativas muito melhores.

Imagem gerada usando ferramentas de IA.

---

🤖 O que é o ZIN MCP Client?

Uma ferramenta poderosa, porém leve, rápida, simples e flexível para interagir com servidores MCP (Model Context Protocol) por meio de LLMs locais. Esta ferramenta permite que você se conecte e utilize várias ferramentas de múltiplos servidores MCP através de uma interface de linha de comando fácil de usar.

Assista às demonstrações!

• Interação CLI rica

https://github.com/user-attachments/assets/fad3d994-8113-47df-b10c-54541a5c3aec

• Realize revisão de código para encontrar vulnerabilidades localmente

https://github.com/user-attachments/assets/4cd26715-b5e6-4b4b-95e4-054de6789f42

• Suporte Plug n Play para Open Web UI

https://github.com/user-attachments/assets/94e1ff33-0c88-40a8-8447-d9c3278a1d50

• Suporta múltiplos servidores - Servidor GhidraMCP

https://github.com/user-attachments/assets/759f7138-1cc5-400f-b7e2-a6a7f0dca894

• Interface web leve

https://github.com/user-attachments/assets/704c214b-0ebb-4da9-971c-5f04446e9646

Funcionalidades

• Suporte a múltiplos servidores: Conecte-se a vários servidores MCP simultaneamente
• Integração com LLM local: Use LLMs locais via Ollama para privacidade e controle
• CLI interativo: Interface de linha de comando limpa e intuitiva com formatação rica
• Interface web mínima e leve: Interface web limpa, mínima e leve para facilidade de uso
• Integração com Open Web UI: Integração Plug n Play com Open Web UI para obter recursos avançados do Open Web UI com um cliente MCP robusto
• Registro abrangente: Logs detalhados para depuração e solução de problemas
• Framework de agente ReAct: Utiliza o padrão de agente ReAct do LangChain para invocar ferramentas de forma inteligente
• Multiplataforma: Suporte multiplataforma
• Simples, rápido, leve: É simples, é rápido, é leve

---

Conheça o Zin MCP Suite

[!NOTE]

Este projeto está em desenvolvimento ativo. Espere mudanças significativas com os lançamentos. Revise o changelog do lançamento antes de atualizar.
Este projeto foi construído principalmente para uso com LLM local para uso pessoal em pequena escala. Expor isso na rede pode representar risco de segurança e, portanto, não é recomendado.
:--------------------------------
Este projeto é desenvolvido principalmente para os servidores Zin MCP, que são os servidores MCP mencionados abaixo, mas o suporte para outros servidores MCP existe e os testes também são realizados em outros servidores MCP, como Ghidra

• APKTool-MCP-Server
• JADX-MCP-Server

🛠️ Começando

1. Baixe dos lançamentos: https://github.com/zinja-coder/zin-mcp-client/releases

# 1. 
unzip zin-mcp-client-<version>.zip

├zin-mcp-client/
  ├── zin_mcp_client.py
  ├── web_client.py
  ├── mcp_proxy.py
  ├── static/
  ├── src/
  ├── mcp-config.json
  ├── README.md
  ├── LICENSE

# 2. Navigate to zin-mcp-client directory
cd zin-mcp-client

# 3. This project uses uv (recommended) - https://github.com/astral-sh/uv instead of pip for dependency management.
    ## a. Install uv (if you dont have it yet) - (Only Required Step)
curl -LsSf https://astral.sh/uv/install.sh | sh

# All below steps are not required.
    ## b. OPTIONAL, if for any reasons, you get dependecy errors in jadx-mcp-server, Set up the environment
uv venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
    ## c. OPTIONAL Install dependencies
uv pip install -r requirements.txt

# 4. Not recommended, you can also use pip for this.
pip install -r requirements.txt
or
pip install -r requirements.txt --break-system-packages

# The setup for zin-mcp-client is done.

🤖 2. Configuração do Ollama

1. Download and Install ollama: https://ollama.com/download

If you are on linux you can directly run below command to install it:

> curl -fsSL https://ollama.com/install.sh | sh

2. Download and run any LLM that has capability to invoke tool.

For example, the llama 3.1 has capability to invoke the tool. 

You can run it using following command:

> ollama run llama3.1:8b

[Note]: Kindly note the above command will fetch the model with 4b parameters. If you have stronger hardware kindly fetch higher parameter model for better performance.

3. Serve the Ollama on API server using following command

> ollama serve

This will serve the ollama api on port 1134, you can confirm that it running using `curl` command as following:

> curl http://localhost:11434/                                                                                                                                              18:54:00
`Ollama is running`

⚙️ 3. Configuração do arquivo de configuração

O arquivo de configuração é o arquivo de configuração do servidor MCP que informa ao cliente MCP Zin como iniciar os servidores MCP.

Ele segue o mesmo estilo do arquivo de configuração do Claude.

Abaixo está o arquivo de configuração de exemplo para os servidores do Zin MCP Suite:

{
    "mcpServers": {
        "jadx-mcp-server": {
            "command": "/path/to/uv", 
            "args": [
                "--directory",
                "/path/to/jadx-mcp-server/",
                "run",
                "jadx_mcp_server.py"
            ]
        },
        "apktool-mcp-server": {
		    "command": "/path/to/uv",
            "args": [
                "--directory",
                "/path/to/apktool-mcp-server/",
                "run",
                "apktool_mcp_server.py"
            ]
	}
    }
}

Substitua:

• path/to/uv pelo caminho real para o seu executável uv
• path/to/jadx-mcp-server pelo caminho absoluto onde você armazenou o jadx-mcp-server

[!NOTE]

A localização padrão do arquivo de configuração está dentro do diretório zin-mcp-client chamado mcp-config.json, no entanto, você pode fornecer o caminho para o seu próprio arquivo de configuração usando a opção --config como

uv run zin_mcp_client.py --server jadx-mcp-server --model llama3.1:8b --config /home/zinjacoder/mcp-config.json 

Experimente

1. Execute o zin_mcp_client.py

uv run zin_mcp_client.py

2. Use a opção --server para especificar o servidor de sua escolha, use a opção --config para fornecer o caminho para o seu arquivo de configuração, use a opção --model para usar um modelo específico, use --debug para habilitar a saída detalhada

Se algo der errado - DEPURAÇÃO e Solução de problemas

[!NOTE]

Para sistemas de baixa especificação, use apenas um servidor por vez para evitar alucinações do LLM.

1. Veja os logs:

• Todos os logs, informações de depuração, tráfego bruto e interações são armazenados em logs de forma fácil de ler. Se algo der errado, verifique os logs.

2. Modo de depuração:

• Você também pode usar o sinalizador --debug para habilitar a depuração e imprimir cada detalhe no console em tempo de execução para ajudar a encontrar o problema.

https://github.com/user-attachments/assets/ee478917-c4f5-46fb-9f0e-ad31d7c33ee0

3. Abra uma issue:

• Se você não conseguir resolver o erro por conta própria, use os logs e a saída do modo de depuração e forneça-os a nós abrindo uma issue em https://github.com/zinja-coder/zin-mcp-client/issues

Cliente Web

1. Conclua a configuração mencionada acima
2. Execute o cliente web usando o seguinte:

uv run web_client.py

3. A demonstração do cliente web é mostrada no vídeo no topo

Configurando com Open Web UI

1. Conclua a configuração mencionada acima.
2. Execute o proxy MCP usando o seguinte:

uv run mcp_proxy.py

3. Vá para o portal Open Web UI.
4. Em Open Web UI -> Configurações -> Conexão -> adicione uma nova conexão conforme mostrado na imagem abaixo

Adicione a URL para o proxy MCP rodando na porta 8000 com localhost se estiver rodando localmente, conforme mostrado na imagem. Você pode colocar qualquer coisa na chave de API.

5. Agora, solicite e utilize o cliente MCP, configuração Plug n Play.

---

Estado Atual do LLM Local e MCPs:

Atualmente, modelos proprietários baseados em API, como o Claude da Anthropic, tendem a ser mais proficientes em chamadas de ferramentas.

No entanto, o mundo de código aberto está avançando rapidamente! Modelos especificamente ajustados em conjuntos de dados de chamadas de funções estão se tornando cada vez mais disponíveis através do Ollama. Pesquisar modelos marcados com function calling ou tool use em plataformas como Hugging Face ou verificar discussões em comunidades como r/LocalLLaMA é fundamental para encontrar opções locais capazes.

---

🛣️ Roteiro Futuro

• Interface web

• Integrar com Open Web UI

• Adicionar suporte a servidores MCP baseados em HTTP - Porque muitos servidores fornecem uma maneira de fazer seus servidores atuarem como baseados em STDIO.

• Adicionar suporte para expor este cliente na rede também, indiretamente para acesso à rede - feito indiretamente via integração com Open Web UI

• Armazenar chat localmente e fornecer histórico de chat - feito indiretamente via integração com Open Web UI

• OBJETIVO FINAL: Tornar todos os servidores MCP de engenharia reversa, reuni-los, para tornar a engenharia reversa o mais fácil possível puramente por vibrações.

Para relatar bugs, problemas, sugestões de recursos, problemas de desempenho, perguntas gerais, problemas de documentação.

• Por favor, abra uma issue com o modelo respectivo.

• Testado em ambientes Mac OS e Linux com jadx-mcp-server, Ghidra MCP Server

🙏 Créditos

Este projeto é possível graças ao ollama, um utilitário incrível para executar LLMs locais. O projeto langchain,

E, por último, agradecimentos a @anthropics por desenvolver o Model Context Protocol e à equipe @FastMCP.

Além disso, um enorme agradecimento a todos os projetos de código aberto que servem como dependências para este projeto e que tornaram isso possível.

📄 Licença

O ZIN MCP Client e todos os projetos relacionados herdam a Licença Apache 2.0.

⚖️ Aviso Legal

Isenção de responsabilidade

As ferramentas zin-mcp-client e zin mcp suite são destinadas estritamente para fins educacionais, de pesquisa e avaliação ética de segurança. Elas são fornecidas "como estão", sem quaisquer garantias, expressas ou implícitas. Os usuários são os únicos responsáveis por garantir que o uso dessas ferramentas esteja em conformidade com todas as leis, regulamentos e diretrizes éticas aplicáveis.

Ao usar zin-mcp-client ou zin mcp suite, você concorda em usá-las apenas em ambientes que está autorizado a testar, como aplicativos que você possui ou tem permissão explícita para analisar. Qualquer uso indevido dessas ferramentas para engenharia reversa não autorizada, violação de direitos de propriedade intelectual ou atividade maliciosa é estritamente proibido.

Os desenvolvedores de zin-mcp-client e zin mcp suite não serão responsabilizados por quaisquer danos, perda de dados, consequências legais ou outras consequências resultantes do uso ou uso indevido dessas ferramentas. Os usuários assumem total responsabilidade por suas ações e qualquer impacto causado pelo seu uso.

Use com responsabilidade. Respeite a propriedade intelectual. Siga práticas éticas de hacking.

---

🙌 Contribua ou Apoie

• Achou útil? Dê uma ⭐️
• Tem ideias? Abra uma issue ou envie um PR
• Construiu algo em cima? Envie uma mensagem ou me mencione — adicionarei ao README!
• Gosta do meu trabalho e quer mantê-lo em andamento? Patrocine este projeto.

---

Feito com ❤️ para as comunidades de engenharia reversa e IA e todos os hackers incríveis e contribuidores de código aberto ao redor do mundo.