Skip to content

Commit 12a6d04

Browse files
strawberry-codestrawberry-code
committed
feat(mcp): aggiunge ragify-mcp come pacchetto PyPI distribuibile via uvx con supporto multi-collection e documentazione dedicata
1 parent f1288b1 commit 12a6d04

File tree

8 files changed

+434
-46
lines changed

8 files changed

+434
-46
lines changed

‎.mcp.json‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
22
"mcpServers": {
33
"ragify": {
4-
"command": "/Users/ccavo001/github/strawberry-code/self-hosted-llm-rag/.venv/bin/python3",
5-
"args": ["/Users/ccavo001/github/strawberry-code/self-hosted-llm-rag/mcp_server.py"],
4+
"command": "uvx",
5+
"args": ["ragify-mcp"],
66
"env": {
77
"QDRANT_URL": "http://127.0.0.1:6333",
88
"OLLAMA_URL": "http://localhost:11434"

‎docs/MCP_SETUP.md‎

Lines changed: 62 additions & 44 deletions
Original file line numberDiff line numberDiff line change
@@ -4,44 +4,45 @@ This guide shows how to configure MCP servers to query your indexed documentatio
44

55
## Server Options
66

7-
There are two MCP server options:
8-
9-
| Server | Language | Multiple Collections | Description |
10-
|--------|----------|---------------------|-------------|
11-
| **Ragify MCP** (recommended) | Python | Yes | Native integration with ragify.py |
12-
| ragdocs (legacy) | Node.js | No | Third-party npm package |
7+
| Server | Language | Multiple Collections | Distribution |
8+
|--------|----------|---------------------|--------------|
9+
| **Ragify MCP** (recommended) | Python | Yes | uvx / PyPI |
10+
| ragdocs (legacy) | Node.js | No | npm |
1311

1412
---
1513

16-
## Option 1: Ragify MCP Server (Recommended)
14+
## Ragify MCP Server (Recommended)
1715

18-
The new native MCP server integrates directly with ragify and supports multiple collections.
16+
The Ragify MCP server supports multiple collections and is distributed as a Python package.
1917

2018
### Prerequisites
2119

22-
- Python 3.10+
20+
- [uv](https://github.com/astral-sh/uv) installed (for uvx)
2321
- Qdrant running with indexed documentation
2422
- Ollama running with nomic-embed-text model
2523

26-
### Installation
24+
### Installation (uvx)
25+
26+
**No installation needed!** uvx downloads and runs the package automatically.
2727

2828
```bash
29-
cd /path/to/self-hosted-llm-rag
30-
pip install -r requirements.txt # Includes mcp[cli]>=1.0.0
29+
# Install uv (one time)
30+
curl -LsSf https://astral.sh/uv/install.sh | sh
3131
```
3232

33-
### Configuration for Claude Desktop / Claude Code
33+
### Configuration
3434

3535
Add to your MCP config:
3636
- **Claude Code**: `.mcp.json` in project root
3737
- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
3838

39+
#### Option A: From PyPI (recommended)
3940
```json
4041
{
4142
"mcpServers": {
4243
"ragify": {
43-
"command": "/path/to/self-hosted-llm-rag/.venv/bin/python3",
44-
"args": ["/path/to/self-hosted-llm-rag/mcp_server.py"],
44+
"command": "uvx",
45+
"args": ["ragify-mcp"],
4546
"env": {
4647
"QDRANT_URL": "http://127.0.0.1:6333",
4748
"OLLAMA_URL": "http://localhost:11434"
@@ -51,7 +52,21 @@ Add to your MCP config:
5152
}
5253
```
5354

54-
**Important:** Use the full path to the Python interpreter in the project's virtual environment (`.venv/bin/python3`), not just `python3`. This ensures the `mcp` module is found.
55+
#### Option B: From local directory (development)
56+
```json
57+
{
58+
"mcpServers": {
59+
"ragify": {
60+
"command": "uvx",
61+
"args": ["--from", "/path/to/self-hosted-llm-rag", "ragify-mcp"],
62+
"env": {
63+
"QDRANT_URL": "http://127.0.0.1:6333",
64+
"OLLAMA_URL": "http://localhost:11434"
65+
}
66+
}
67+
}
68+
}
69+
```
5570

5671
Replace `/path/to/self-hosted-llm-rag` with your actual path.
5772

@@ -65,7 +80,7 @@ Replace `/path/to/self-hosted-llm-rag` with your actual path.
6580

6681
### Usage Examples
6782

68-
In Claude Desktop or Claude Code, you can use:
83+
In Claude Desktop or Claude Code:
6984

7085
- "Search for authentication in the matematica collection"
7186
- "List all available collections"
@@ -74,19 +89,21 @@ In Claude Desktop or Claude Code, you can use:
7489
### Development & Testing
7590

7691
```bash
92+
# Test locally with uvx
93+
uvx --from . ragify-mcp
94+
95+
# Or install in development mode
96+
pip install -e .
97+
ragify-mcp
98+
7799
# Test with MCP Inspector
78100
pip install "mcp[cli]"
79-
mcp dev mcp_server.py
80-
81-
# In the Inspector, test tools:
82-
# - list_collections()
83-
# - search_documentation("your query", "collection_name", 5)
84-
# - list_sources("collection_name")
101+
mcp dev src/ragify_mcp/server.py
85102
```
86103

87104
---
88105

89-
## Option 2: ragdocs (Legacy)
106+
## ragdocs (Legacy)
90107

91108
The original npm-based MCP server. **Note:** This server only supports a single hardcoded collection.
92109

@@ -96,7 +113,7 @@ The original npm-based MCP server. **Note:** This server only supports a single
96113
npm install -g @qpd-v/mcp-server-ragdocs
97114
```
98115

99-
### Configuration for Claude Desktop
116+
### Configuration
100117

101118
```json
102119
{
@@ -114,16 +131,6 @@ npm install -g @qpd-v/mcp-server-ragdocs
114131
}
115132
```
116133

117-
**Finding paths:**
118-
119-
```bash
120-
# Find node path
121-
which node
122-
123-
# Find global node_modules
124-
npm root -g
125-
```
126-
127134
---
128135

129136
## Environment Variables
@@ -138,22 +145,19 @@ npm root -g
138145

139146
## Working with Multiple Collections
140147

141-
With Ragify MCP, you can work with multiple collections:
148+
Index documents into different collections:
142149

143150
```bash
144-
# Index documents into different collections
145151
python3 ragify.py index ./docs/matematica # Creates collection "matematica"
146152
python3 ragify.py index ./docs/fisica # Creates collection "fisica"
147-
python3 ragify.py index ./docs/chimica # Creates collection "chimica"
148153

149154
# Or specify collection manually
150155
python3 ragify.py index ./docs --collection my_custom_name
151156
```
152157

153-
Then query specific collections:
158+
Query specific collections in Claude:
154159

155160
```
156-
# In Claude Desktop/Code
157161
"Search for 'integral' in the matematica collection"
158162
"List all sources in fisica"
159163
```
@@ -164,9 +168,9 @@ Then query specific collections:
164168

165169
### MCP Server not appearing
166170

167-
1. Verify paths are correct (absolute paths required)
171+
1. Restart your MCP client after config changes
168172
2. Check environment variables are set correctly
169-
3. Restart your MCP client
173+
3. Verify uv is installed: `uv --version`
170174

171175
### Connection errors
172176

@@ -180,7 +184,7 @@ curl http://localhost:11434/api/tags
180184

181185
### Collection not found
182186

183-
Make sure you've indexed documents with ragify first:
187+
Index documents first:
184188

185189
```bash
186190
python3 ragify.py index ./docs
@@ -189,7 +193,21 @@ python3 ragify.py list # Verify indexing
189193

190194
---
191195

196+
## Publishing to PyPI (for maintainers)
197+
198+
```bash
199+
# Build
200+
pip install build
201+
python -m build
202+
203+
# Upload to PyPI
204+
pip install twine
205+
twine upload dist/*
206+
```
207+
208+
---
209+
192210
## More Information
193211

194212
- [MCP Protocol Documentation](https://modelcontextprotocol.io/)
195-
- [Ragify Documentation](RAGIFY.md)
213+
- [uv Documentation](https://github.com/astral-sh/uv)

‎pyproject.toml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
[project]
2+
name = "ragify-mcp"
3+
version = "1.0.1"
4+
description = "MCP Server for RAG documentation search with Qdrant and Ollama"
5+
readme = "src/ragify_mcp/README.md"
6+
license = {text = "MIT"}
7+
requires-python = ">=3.10"
8+
keywords = ["mcp", "rag", "qdrant", "ollama", "semantic-search", "vector-database"]
9+
classifiers = [
10+
"Development Status :: 4 - Beta",
11+
"Intended Audience :: Developers",
12+
"License :: OSI Approved :: MIT License",
13+
"Programming Language :: Python :: 3.10",
14+
"Programming Language :: Python :: 3.11",
15+
"Programming Language :: Python :: 3.12",
16+
"Topic :: Scientific/Engineering :: Artificial Intelligence",
17+
]
18+
19+
dependencies = [
20+
"mcp>=1.0.0",
21+
"qdrant-client>=1.7.0",
22+
"requests>=2.31.0",
23+
]
24+
25+
[project.scripts]
26+
ragify-mcp = "ragify_mcp:main"
27+
28+
[project.urls]
29+
Homepage = "https://github.com/strawberry-code/self-hosted-llm-rag"
30+
Repository = "https://github.com/strawberry-code/self-hosted-llm-rag"
31+
Documentation = "https://github.com/strawberry-code/self-hosted-llm-rag/blob/main/docs/MCP_SETUP.md"
32+
33+
[build-system]
34+
requires = ["hatchling"]
35+
build-backend = "hatchling.build"
36+
37+
[tool.hatch.build.targets.wheel]
38+
packages = ["src/ragify_mcp"]
39+
40+
[tool.hatch.build.targets.sdist]
41+
include = [
42+
"src/ragify_mcp/",
43+
"pyproject.toml",
44+
"LICENSE",
45+
]

‎src/ragify_mcp/README.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# ragify-mcp
2+
3+
MCP Server for semantic documentation search using Qdrant and Ollama.
4+
5+
## Installation
6+
7+
No installation needed with uvx:
8+
9+
```bash
10+
uvx ragify-mcp
11+
```
12+
13+
Or install via pip:
14+
15+
```bash
16+
pip install ragify-mcp
17+
```
18+
19+
## Configuration
20+
21+
Add to your MCP client config (Claude Desktop or Claude Code):
22+
23+
```json
24+
{
25+
"mcpServers": {
26+
"ragify": {
27+
"command": "uvx",
28+
"args": ["ragify-mcp"],
29+
"env": {
30+
"QDRANT_URL": "http://127.0.0.1:6333",
31+
"OLLAMA_URL": "http://localhost:11434"
32+
}
33+
}
34+
}
35+
}
36+
```
37+
38+
## Prerequisites
39+
40+
- Qdrant running with indexed documentation
41+
- Ollama running with `nomic-embed-text` model
42+
43+
## Available Tools
44+
45+
| Tool | Description |
46+
|------|-------------|
47+
| `search_documentation` | Semantic search in a collection |
48+
| `list_collections` | List all available collections |
49+
| `list_sources` | List indexed files in a collection |
50+
51+
## Environment Variables
52+
53+
| Variable | Default | Description |
54+
|----------|---------|-------------|
55+
| `QDRANT_URL` | http://localhost:6333 | Qdrant server URL |
56+
| `QDRANT_API_KEY` | - | Optional API key for Qdrant Cloud |
57+
| `OLLAMA_URL` | http://localhost:11434 | Ollama server URL |
58+
59+
## Part of Ragify
60+
61+
This MCP server is part of the [Ragify](https://github.com/strawberry-code/self-hosted-llm-rag) project - a self-hosted RAG system for indexing and querying documentation.
62+
63+
## License
64+
65+
MIT

‎src/ragify_mcp/__init__.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
"""
2+
ragify-mcp: MCP Server for RAG documentation search with Qdrant and Ollama.
3+
"""
4+
5+
from .server import main
6+
7+
__version__ = "1.0.1"
8+
__all__ = ["main"]

‎src/ragify_mcp/__main__.py‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
"""
2+
Allow running as: python -m ragify_mcp
3+
"""
4+
5+
from .server import main
6+
7+
if __name__ == "__main__":
8+
main()

0 commit comments

Comments
 (0)