RAG FAQ

You have an MCP server starter that exposes an FAQ-based RAG tool. It loads a tiny FAQ corpus and serves retrieval augmented answers through a standard MCP interface, enabling you to query FAQs and see relevant content with a ready-to-use prompt flow. This setup prioritizes simplicity, practicality, and interface correctness so you can iterate quickly on retrieval quality and prompt behavior.

How to use

Spawn the MCP server locally and connect a client to it. You will run a Python-based stdio MCP server that is started by your MCP client and communicates through the standard MCP protocol. You can customize the server startup by setting your API key and optional model overrides as needed.

How to install

Prerequisites: you need Python and a functioning internet connection to install dependencies and run the server.

1. Create and activate a Python virtual environment.

python -m venv .venv
source .venv/bin/activate

2. Install the required Python packages.

pip install -r requirements.txt

3. Set your OpenAI API key. This enables the RAG and FAQ retrieval to function.

export OPENAI_API_KEY=sk-...

4. (Optional) Override models if you want to customize the embedding or LLM behavior.

# export EMBED_MODEL=text-embedding-ada-002
# export LLM_MODEL=gpt-3.5-turbo

5. Run the RAG core to verify the setup works.

python rag_core.py

6. Start the MCP server using the provided spawn configuration from your MCP client.

# Example MCP spawn configuration shown to you by the client:
# command: python
# args: [/absolute/path/to/mcp_server.py]
# env: { OPENAI_API_KEY: "sk-..." }

Configuration and runtime details

The MCP client will spawn the server with a Python command and a path to the MCP server script. You will typically set the OPENAI_API_KEY in your environment so the server can access OpenAI services for both embedding calculations and LLM calls.

The server exposes the following core capabilities we rely on for the FAQ-based RAG flow: a retrieval step that uses in-memory cosine similarity to rank FAQs, and a prompt flow that includes an ask_faq_expert context to help the LLM interpret results effectively.

Security and operation notes

Keep your API key secure and do not expose it in logs or command histories. If you share your configuration, redact the key value and use environment variables or secret managers provided by your runtime.

Monitor basic logs for errors related to API rate limits or missing resources, and ensure the FAQ corpus in FAQs/ remains accessible to the server process.

Troubleshooting tips

If you encounter issues starting the MCP server, verify that Python can locate the mcp_server.py script and that the OPENAI_API_KEY environment variable is set for the process that runs the server.

If retrieval returns incorrect results, ensure the in-memory FAQ corpus is loaded correctly and that the embedding model is functioning as expected. You can temporarily print debug information from rag_core.py to inspect similarity scores and top results.

Notes and best practices

This starter uses a lightweight, dependency-light approach to enable fast iteration. There is no external vector database; we rely on numpy-based cosine similarity for quick retrieval. The MCP interface is designed to be straightforward, exposing tools, resources, and prompts so you can validate the flow end-to-end.

Available tools

rag_core

RAG core logic that performs embedding-based retrieval and similarity scoring using in-memory cosine similarity.

mcp_server

MCP server component that exposes ask_faq and handles the standard MCP protocol integration.

faq_resource

Resource access to the raw FAQ content via the faq:// resource for debugging and verification.

ask_faq_expert

Predefined prompt to ensure the LLM starts with the right context when handling FAQ queries.