convez.ai
MCP Server
Sushmender

MCP_1

Sushmender/MCP_1

Ver no GitHub
InicialPluginScore · de 0 a 100

Basic project on MCP client and server config

Instalação

$npx convez-ai Sushmender/MCP_1

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 meses
Versão
—
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

🔬 MCP Research Backend

A production-ready FastAPI backend that connects to multiple Model Context Protocol (MCP) servers and exposes a unified REST API for AI-powered academic research. The system lets an LLM autonomously search arXiv, manage local paper archives, fetch web content, and read/write files — all orchestrated through the MCP tool-calling loop.


✨ Features

  • Multi-LLM Support — Plug-and-play provider switching between Groq, Cerebras, and Anthropic
  • MCP Tool Orchestration — LLM autonomously calls tools across multiple MCP servers until it produces a final answer
  • arXiv Research Tools — Search papers, extract metadata, and persist results locally
  • Filesystem Access — Read/write files in the papers/ directory via the official MCP filesystem server
  • Web Fetching — Fetch and read live web pages via the MCP fetch server
  • Reusable Prompts — Pre-built research prompt templates (summarize, compare, find & summarize)
  • Resource Endpoints — Browse locally cached papers by topic without calling any tool
  • Interactive API Docs — Swagger UI available out of the box at /docs

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│                   FastAPI Backend                   │
│  POST /api/chat   GET /api/tools   /api/prompts     │
│  POST /api/prompts/execute   GET /api/resources     │
└───────────────────┬─────────────────────────────────┘
                    │ MCPClientManager
          ┌─────────┼─────────────────┐
          │         │                 │
   ┌──────▼──┐ ┌────▼──────┐ ┌───────▼──┐
   │research │ │filesystem │ │  fetch   │
   │  MCP    │ │  MCP      │ │  MCP     │
   │ server  │ │  server   │ │  server  │
   └──────┬──┘ └────┬──────┘ └───────┬──┘
          │         │                 │
     arXiv API  ./papers dir    HTTP web

Directory Structure

MCP_1/
├── app/
│   ├── main.py              # FastAPI app + lifespan (startup/shutdown)
│   ├── config.py            # Settings loaded from .env
│   ├── mcp_client.py        # MCPClientManager — connects to servers, runs LLM loop
│   ├── api/
│   │   └── endpoints.py     # REST endpoints: /chat, /tools, /prompts, /resources
│   ├── llm/
│   │   ├── base.py          # Abstract BaseLLMProvider
│   │   ├── factory.py       # get_llm_provider() factory
│   │   ├── groq_provider.py     # Groq (llama-3.3-70b-versatile, etc.)
│   │   ├── cerebras_provider.py # Cerebras (gpt-oss-120b, etc.)
│   │   └── anthropic_provider.py# Anthropic (claude-3-7-sonnet, etc.)
│   └── schemas/
│       └── chat.py          # Pydantic request/response models
├── research_server.py       # Custom MCP server (tools, resources, prompts)
├── server_config.json       # MCP server process definitions
├── papers/                  # Auto-created; stores downloaded paper metadata
│   └── <topic>/
│       └── papers_info.json
├── docs/                    # Learning notebooks & walkthroughs
├── requirements.txt
├── .env.example             # Copy to .env and fill in your keys
└── .gitignore

🚀 Quick Start

1. Clone & enter the project

git clone <your-repo-url>
cd MCP_1

2. Create and activate a virtual environment

# Windows
python -m venv .venv
.venv\Scripts\activate

# macOS / Linux
python -m venv .venv
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure environment variables

# Copy the example file
copy .env.example .env    # Windows
cp .env.example .env      # macOS / Linux

Open .env and fill in at minimum the LLM provider and API key you want to use:

# Choose one: cerebras | groq | anthropic
LLM_PROVIDER=groq

# Groq
GROQ_API_KEY=your_groq_api_key_here
GROQ_MODEL=llama-3.3-70b-versatile

# Cerebras (optional)
CEREBRAS_API_KEY=your_cerebras_api_key_here
CEREBRAS_MODEL=gpt-oss-120b

# Anthropic (optional)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
ANTHROPIC_MODEL=claude-3-7-sonnet-20250219

Get free API keys:

5. Start the server

uvicorn app.main:app --reload

The server starts at http://127.0.0.1:8000.

On startup you will see the MCP servers connecting and registering their tools:

Initializing MCP Client Manager and connecting to servers...
[LLM] Provider: GROQ  |  Model: llama-3.3-70b-versatile
[LLM] Provider initialized successfully.
Connecting to MCP Server 'research'...
Connected to 'research' successfully. Registered tools: ['search_papers', 'extract_info']
Connecting to MCP Server 'filesystem'...
Connected to 'filesystem' successfully. Registered tools: [...]
Connecting to MCP Server 'fetch'...
Connected to 'fetch' successfully. Registered tools: ['fetch']
INFO:     Application startup complete.

📡 API Reference

Interactive Swagger UI: http://127.0.0.1:8000/docs

POST /api/chat

Send any free-form query. The LLM decides which tools to call.

// Request
{ "message": "Find me the top 3 papers on transformer attention mechanisms and summarize them." }

// Response
{
  "response": "Here are the top 3 papers on transformer attention mechanisms...",
  "tool_calls": [
    { "id": "call_abc", "name": "search_papers", "input": { "topic": "transformer attention mechanisms", "max_results": 3 } },
    { "id": "call_def", "name": "extract_info",  "input": { "paper_id": "2301.01234" } }
  ]
}

GET /api/tools

List all tools registered across every connected MCP server.

GET /api/prompts

List all named prompts available (e.g. summarize_paper, compare_papers, find_and_summarize).

POST /api/prompts/execute

Execute a named MCP prompt template and pipe its output through the LLM.

// Summarize a single paper
{ "prompt_name": "summarize_paper", "arguments": { "paper_id": "2301.01234" } }

// Compare two papers
{ "prompt_name": "compare_papers", "arguments": { "paper_id_1": "2301.01234", "paper_id_2": "2302.05678" } }

// Search and summarize a topic
{ "prompt_name": "find_and_summarize", "arguments": { "topic": "RAG", "max_results": 3 } }

GET /api/resources

List all static resources and URI templates registered by MCP servers.

GET /api/resources/read?uri=<uri>

Read a specific resource by its URI.

GET /api/resources/read?uri=papers://list
GET /api/resources/read?uri=papers://transformer_attention_mechanisms/info

🔧 MCP Servers

The backend connects to three MCP servers defined in server_config.json:

ServerCommandProvides
researchpython research_server.pysearch_papers, extract_info tools; papers://list resource; 3 prompts
filesystemnpx @modelcontextprotocol/server-filesystem ./papersFull file read/write access to the papers/ directory
fetchuvx mcp-server-fetchfetch tool — retrieves live web pages

Research Server Tools

ToolDescription
search_papers(topic, max_results=5)Searches arXiv, stores metadata in papers/<topic>/papers_info.json, returns list of paper IDs
extract_info(paper_id)Looks up stored metadata for a given arXiv paper ID

Research Server Resources

URIDescription
papers://listJSON map of all stored topics → paper IDs
papers://{topic}/infoFull metadata for all papers under a given topic

Research Server Prompts

PromptArgsDescription
summarize_paperpaper_idGenerates instructions to summarize a paper
compare_paperspaper_id_1, paper_id_2Generates instructions to compare two papers
find_and_summarizetopic, max_results=3Generates instructions to search and summarize

🤖 LLM Providers

Switch providers at any time by changing LLM_PROVIDER in your .env file and restarting.

ProviderLLM_PROVIDER valueDefault ModelNotes
Groqgroqllama-3.3-70b-versatileFast inference, good tool-calling
Cerebrascerebrasgpt-oss-120bUltra-fast, best for long contexts
Anthropicanthropicclaude-3-7-sonnet-20250219Best reasoning, native tool-calling

All providers implement BaseLLMProvider and return the same normalized response format, so the rest of the system is completely provider-agnostic.


⚙️ Configuration Reference

All settings live in .env (copy from .env.example):

VariableDefaultDescription
LLM_PROVIDERcerebrasActive provider: cerebras, groq, or anthropic
GROQ_API_KEY—Your Groq API key
GROQ_MODELllama-3.3-70b-versatileGroq model name
CEREBRAS_API_KEY—Your Cerebras API key
CEREBRAS_MODELgpt-oss-120bCerebras model name
ANTHROPIC_API_KEY—Your Anthropic API key
ANTHROPIC_MODELclaude-3-7-sonnet-20250219Anthropic model name
HOST127.0.0.1Uvicorn bind address
PORT8000Uvicorn port
LOG_LEVELinfoUvicorn log level
PROMPT_TIMEOUT_SECS300Max seconds for a prompt/chat request
SERVER_CONFIG_PATHserver_config.jsonPath to MCP server definitions

📦 Dependencies

PackagePurpose
fastapiWeb framework
uvicornASGI server
mcpModel Context Protocol SDK (client + server)
arxivarXiv API client
groqGroq Python SDK
cerebras-cloud-sdkCerebras Python SDK
anthropicAnthropic Python SDK
python-dotenv.env file loading
pydanticRequest/response validation
nest-asyncioAsync loop compatibility

📚 Learning Resources

The docs/ directory contains Jupyter notebooks used during development:

  • L4.ipynb — MCP client basics
  • L5.ipynb — Tool calling patterns
  • L6.ipynb — Advanced orchestration
  • mcp_chatbot.py — Standalone script version of the chatbot
  • walkthrough.md — Step-by-step build walkthrough

🛠️ Development Tips

Hot reload is enabled by default with --reload. Any changes to Python files will automatically restart the server.

View all available tools at runtime:

curl http://127.0.0.1:8000/api/tools

Increase timeout for complex queries (e.g., comparing papers that haven't been cached yet):

PROMPT_TIMEOUT_SECS=600

Papers are cached locally in papers/<topic>/papers_info.json. Subsequent queries for the same topic are faster since metadata is already on disk.

Ver o original no GitHub

Relacionados