guides/GETTING_STARTED.md

Getting Started with Docs Navigator MCP

Welcome! This guide will walk you through setting up and using the Docs Navigator MCP system step by step. By the end, you'll have a working AI assistant that can answer questions about your documentation.

📋 Prerequisites

Before you begin, make sure you have:

• Python 3.10+ installed on your system
• An Anthropic API key (sign up at console.anthropic.com)
• Command line access (Terminal on macOS/Linux, Command Prompt on Windows)
• UV package manager (recommended) or pip

Installing UV (Recommended)

UV provides faster dependency management than pip:

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

🛠️ Step-by-Step Setup

Step 1: Get the Code

Clone or download this repository:

git clone <your-repo-url>
cd docs-navigator

Step 2: Set Up Python Environment

Using UV (recommended):

uv sync

Using pip:

# Create virtual environment
python -m venv .venv

# Activate it
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Step 3: Configure Your API Key

Create a .env file in the project root:

# Create the file
touch .env  # On macOS/Linux
# Or just create the file manually on Windows

Add your Anthropic API key to the .env file:

ANTHROPIC_API_KEY= your-actual-api-key-here

Important: Never commit your .env file to version control!

Step 4: Verify Your API Key

Test that your API key works:

# Using UV
uv run test_anthropic.py

# Using Python directly
python test_anthropic.py

You should see output like:

Testing model: claude-3-haiku-20240307
✅ claude-3-haiku-20240307: API working
Done testing models.

Step 5: Add Your Documentation

Place your documentation files in the docs/ folder. The system supports:

• Markdown files (.md)
• Text files (.txt)
• reStructuredText files (.rst)

Example structure:

docs/
├── getting-started.md
├── api-reference.md
├── troubleshooting.txt
├── faq.md
└── installation.rst

Sample content to try: The project already includes sample docs you can test with:

• overview.md
• setup.md
• troubleshooting.md
• prompting-guidelines.md
• auroraai_report.txt

Step 6: Test the MCP Server

Verify that the MCP server can read your docs:

# Using UV
uv run test_mcp.py

# Using Python directly
python test_mcp.py

Expected output:

Connecting to MCP server...
Listing available docs...
Available tools: ['list_docs', 'search_docs']
Available docs: [overview.md, setup.md, ...]
Search results for 'setup': [{"path": "setup.md", "snippet": "..."}]
✅ MCP connection and tools working correctly!

Step 7: Test End-to-End Functionality

Run a complete test:

# Using UV
uv run test_complete.py

# Using Python directly
python test_complete.py

This will ask the AI a question about your docs and show you the response.

Step 8: Launch the Web Interface

Start the Gradio app:

# Using UV
uv run app_gradio.py

# Using Python directly
python app_gradio.py

You'll see:

* Running on local URL:  http://127.0.0.1:7860
* To create a public link, set `share=True` in `launch()`.

Open http://127.0.0.1:7860 in your browser.

💬 Using the Chat Interface

Once the web interface opens, you can:

Example Questions to Try:

1. Discovery: "What documentation do you have available?"

2. Specific lookup: "How do I set up authentication?"

3. Troubleshooting: "What should I do if I get connection errors?"

4. Summarization: "Give me an overview of the main features"

5. Search: "Find information about API endpoints"

How It Works:

1. You ask a question in the chat interface
2. The AI agent receives your question
3. MCP tools search through your documentation files
4. Claude AI analyzes the search results
5. You get an answer with references to source files

🔍 Understanding the Components

Files You'll Work With:

• app_gradio.py: The web interface (you probably won't need to modify this)
• client_agent.py: Connects to Claude AI and MCP server
• server_docs.py: Provides document search tools to the AI
• docs/: Your documentation files go here
• .env: Your API key and other secrets

What Happens When You Ask a Question:

Your Question → Gradio → Client Agent → Claude AI
                                         ↓
                                    "I need to search docs"
                                         ↓
                                    MCP Server → docs/ folder
                                         ↓
                                    Search Results
                                         ↓
                               Claude AI (generates answer)
                                         ↓
                              Gradio → Your Answer

⚙️ Customization Options

Change the AI Model

Edit client_agent.py and modify the model name:

model="claude-3-haiku-20240307"  # Current model
model="claude-3-5-sonnet-20241022"  # Higher quality (requires API access)

Change the Port

Edit app_gradio.py:

demo.launch()  # Default port 7860
demo.launch(server_port=8080)  # Custom port

Add More File Types

Edit server_docs.py:

exts = {".md", ".txt", ".rst"}  # Current formats
exts = {".md", ".txt", ".rst", ".pdf", ".docx"}  # Add more (requires additional code)

🐛 Troubleshooting Common Issues

"Model not found" Error

Problem: Your API key doesn't have access to the specified Claude model.

Solution: The system will automatically test and find a working model. If this fails, check that your API key is valid.

"No such file or directory" Error

Problem: Python path or virtual environment issues.

Solution:

# Make sure you're in the right directory
pwd  # Should show /path/to/docs-navigator

# Make sure virtual environment is activated
which python  # Should show .venv path

No Documents Found

Problem: The system can't find your documentation files.

Solution:

• Check that files are in the docs/ folder
• Verify file extensions (.md, .txt, .rst)
• Check file permissions

Port Already in Use

Problem: Port 7860 is already taken.

Solution:

• Stop other applications using the port
• Or change the port in app_gradio.py

Connection Refused

Problem: MCP server can't start.

Solution:

• Check that server_docs.py is executable
• Verify all dependencies are installed
• Check for Python syntax errors

📈 Next Steps

Once you have the basic system working:

1. Add more documentation: Populate the docs/ folder with your content

2. Customize prompts: Modify the system prompts in client_agent.py to better suit your use case

3. Improve search: Enhance the search functionality in server_docs.py

4. Add more tools: Create additional MCP tools for specific documentation tasks

5. Deploy: Set up the system on a server for team access

💡 Tips for Better Results

Organizing Your Docs:

• Use clear, descriptive filenames
• Include section headings in markdown
• Keep related information in the same file
• Use consistent terminology

Writing Good Questions:

• Be specific about what you need
• Reference topics from your documentation
• Ask for examples when appropriate
• Request sources for verification

Optimizing Performance:

• Keep individual doc files reasonably sized
• Use markdown headers for better structure
• Remove irrelevant or outdated content
• Test questions regularly to improve prompts

🆘 Getting Help

If you run into issues:

1. Check the test scripts: Run test_mcp.py and test_anthropic.py
2. Review the logs: Look for error messages in the terminal
3. Verify your setup: Double-check API keys and file paths
4. Start fresh: Create a new virtual environment if needed

🎉 Success!

You should now have a working documentation assistant! The AI can search through your docs and provide intelligent answers to your questions.

Try asking: "What can you help me with?" to get started!