# MCP Doc Search

# MCP Document Search Server

## Overview

This project was built as a hands-on exercise to understand the Model Context Protocol (MCP) by implementing all three core MCP primitives:

* Prompts
* Tools
* Resources

The final outcome is a simple documentation search MCP server that exposes:

* A `search_docs` tool for searching documentation
* Dynamic resources representing documents stored in a local `docs/` folder

The server can be tested and explored using the MCP Inspector.

---

## MCP Concepts Learned

### 1. Prompts

Prompts are reusable instruction templates exposed by an MCP server.

Pattern:

* `prompts/list`
* `prompts/get`

Example:

```text
simple
```

A client can discover available prompts and retrieve the prompt content.

---

### 2. Tools

Tools expose executable functionality.

Pattern:

* `tools/list`
* `tools/call`

Examples implemented during learning:

```text
fetch
add
multiply
search_docs
```

A tool receives arguments, performs some action, and returns structured results.

---

### 3. Resources

Resources expose data that can be read by a client.

Pattern:

* `resources/list`
* `resources/read`

````

Examples:

```text
docs://mcp
docs://architecture
docs://retrieval
````

Resources represent existing data and are analogous to files or documents.

---

## MCP Mental Model

```text
Tool     = Function
Resource = File
Prompt   = Template
```

Examples:

```text
search_docs("MCP")      -> Tool
docs://mcp             -> Resource
code-review-template   -> Prompt
```

---

## Current Architecture

```text
MCP Client
    │
    ├── search_docs(query)      [Tool]
    │
    └── docs://*                [Resources]
              │
              └── read_resource()
```

### Search Flow

```text
User Query
    ↓
search_docs("MCP")
    ↓
Returns matching resource URIs
    ↓
docs://mcp
    ↓
read_resource("docs://mcp")
    ↓
Returns document content
```

This demonstrates the common MCP pattern:

```text
Tool → Resource Chain
```

---

## Project Structure

```text
doc-search/
│
├── README.md
├── pyproject.toml
│
└── mcp_doc_search/
    │
    ├── __init__.py
    ├── __main__.py
    ├── server.py
    │
    └── docs/
        ├── architecture.txt
        ├── retrieval.txt
        └── mcp.txt
```

---

## Features

### Tool: search_docs

Input:

```json
{
  "query": "MCP"
}
```

Behavior:

* Searches all `.txt` files in the `docs` directory
* Performs a case-insensitive search
* Returns matching resource URIs

Example output:

```text
docs://mcp
```

---

### Resources

Resources are generated dynamically from the `docs` directory.

Examples:

```text
docs://mcp
docs://architecture
docs://retrieval
```

Reading a resource returns the document content.

---

## Testing

The server can be tested using MCP Inspector.

Example configuration:

Command:

```text
uv
```

Arguments:

```text
run python -m mcp_doc_search
```

The Inspector can then:

* List tools
* Call `search_docs`
* List resources
* Read resources

---

## Key Takeaways

* MCP follows a consistent discovery and execution pattern.
* Tools are used for actions and discovery.
* Resources are used for retrieving known content.
* Prompts are reusable instruction templates.
* Many knowledge and retrieval servers follow a Tool → Resource architecture.
* The MCP layer remains stable even when the retrieval implementation evolves from simple file search to BM25, vector search, hybrid search, or databases.

---

## Future Improvements

* BM25 search
* Vector search
* Hybrid search
* SingleStore integration
* Result ranking and scoring
* Resource metadata
* Claude Desktop / Cursor integration
* Retrieval-Augmented Generation (RAG)

-- -----------------

create venv: uv venv
Go to correct toml file and run: uv sync
uv run python -m mcp_simple_prompt --help
>uv run python -m mcp_doc_search --help

Install inspector: npx @modelcontextprotocol/inspector and runs it port:6274
(For stdio transport, Inspector itself launches the server, so need not run uv run mcp-simple-prompt in another terminal)
or run
python
-m
mcp_doc_search in the arguments

Enter the proxy token or launch the Proxy configured url and enter-> Command: uv and arguments: run mcp-simple-prompt