Criei um Servidor MCP para Meu Portfólio

A solução óbvia para "meus projetos parecem todos iguais" é um README melhor — mais capturas de tela, descrições mais claras, talvez uma tabela de comparação. Eu considerei isso por cerca de cinco minutos e decidi que ainda era apenas uma lista de links mais bonita.

O que realmente fez um projeto de portfólio parecer diferente foi torná-lo algo com o qual você poderia conversar em vez de ler. É para isso que o MCP (Modelo de Protocolo de Contexto) foi criado — é o padrão que permite que clientes de IA como o Claude Desktop chamem ferramentas externas diretamente, não apenas processem texto. Então, eu construí um servidor que expõe meus 9 projetos como ferramentas consultáveis em vez de entradas estáticas.

O que é MCP e por que isso importa aqui

Quase todo portfólio de desenvolvedor de IA que eu vi é uma lista de links. O meu agora inclui algo com o qual você pode realmente conversar. Abra o Claude Desktop, conecte meu servidor e pergunte "o que Ayush construiu com FastAPI?" — ele não adivinha a partir de um README em cache, ele chama uma ferramenta real e responde com dados estruturados e ao vivo.

O que eu construí

Um servidor MCP em Python (FastMCP, transporte stdio) expondo cinco ferramentas:

• list_projects — resumo curto de todos os 9 projetos
• get_project_details(project_name) — pilha completa, link do GitHub, URL de demonstração para um projeto, correspondido de forma imprecisa pelo nome
• search_projects_by_stack(technology) — "mostre-me tudo usando Groq" ou "LangGraph" ou "React"
• get_flagship_project — o melhor projeto para olhar primeiro
• get_resume_summary — histórico, função alvo, pilha principal

Os dados em si vivem em dicionários Python simples neste momento — nenhum banco de dados necessário para algo desse tamanho. Cada ferramenta é uma função fina em torno desses dados, decorada com @mcp.tool().

@mcp.tool()
def search_projects_by_stack(technology: str) -> list[dict]:
    """Encontre todos os projetos que usam uma determinada tecnologia ou ferramenta."""
    query = technology.lower().strip()
    matches = [
        {"name": p["name"], "stack": p["stack"], "github": p["github"]}
        for p in PROJECTS
        if any(query in tech.lower() for tech in p["stack"])
    ]
    return matches or [{"message": f"Nenhum projeto encontrado usando '{technology}'"}]

O que realmente quebrou

O conceito é simples. A configuração teve quatro buracos separados:

1. O MCP Inspector padrão para uv, não Python simples. Executar mcp dev server.py abre uma interface que assume que seu projeto usa o gerenciador de pacotes uv por padrão. Se você estiver em uma configuração simples de venv + pip, o campo de comando precisa ser alterado manualmente para python com server.py como argumento, ou nunca se conecta.

2. O Claude Desktop como um aplicativo da Windows Store usa um caminho de configuração completamente diferente. Eu o instalei via Microsoft Store primeiro. As instruções de configuração padrão apontam para %APPDATA%\Claude\claude_desktop_config.json — que não existe para a versão da Store, que armazena sua configuração em algum lugar sob AppData\Local\Packages\... em vez disso. Desinstalar e reinstalar o .exe direto de claude.ai/download resolveu isso.

3. Dois arquivos de configuração quase idênticos. Uma vez que o aplicativo real foi instalado, há um arquivo de trecho de configuração na sua própria pasta de projeto (para referência) e o arquivo de configuração real do aplicativo (encontrado via Configurações → Desenvolvedor → Editar Config). Eles podem parecer idênticos à primeira vista. Eu editei o errado duas vezes antes de notar o breadcrumb da aba mostrando qual era o real.

4. O modelo não chama sempre sua ferramenta apenas porque está conectado. Meu primeiro teste — "quais projetos Ayush construiu com FastAPI?" — foi respondido pela própria suposição interna do Claude em vez de realmente chamar meu servidor, e obteve um detalhe errado como resultado (chamou o ResumeIQ de um projeto FastAPI; é Flask). Nomear a ferramenta ou servidor explicitamente no prompt ("use a ferramenta de portfólio para pesquisar...") forçou uma chamada real da ferramenta, que então retornou dados corretos todas as vezes.

Vendo funcionar

Uma vez conectado, é assim que uma sessão real se parece:

Eu: Qual é o projeto principal de Ayush e por quê?

(Claude Desktop mostra: "Claude quer usar Obter projeto principal do portfólio" — Sempre Permitir / Negar)

Claude: Seu projeto principal é SalesAgent — um agente de vendas B2B autônomo que pega uma URL do LinkedIn, pesquisa o lead, os classifica com um modelo de ML (84/100 de precisão) e redige um e-mail frio hiperpersonalizado, tudo em menos de 45 segundos. Por que é o principal: complexidade de pilha completa (LangGraph + FastAPI + React + pontuação scikit-learn), não uma fina camada de API em torno de uma chamada LLM...

Esse diálogo de permissão é importante — é a prova de que isso é uma chamada de ferramenta real e isolada acontecendo ao vivo, não uma resposta roteirizada.

Experimente você mesmo

Repo: https://github.com/ayush-s-tomar/portfolio-mcp-server
Conecte-o ao seu próprio Claude Desktop em menos de 10 minutos — instruções completas de configuração no README.

Se você está construindo um portfólio de desenvolvedor de IA e cada projeto que você tem parece a mesma forma que o anterior, esta é uma maneira barata de adicionar algo estruturalmente.