flexible-graphrag-mcp 0.4.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- flexible_graphrag_mcp-0.4.0/PKG-INFO +345 -0
- flexible_graphrag_mcp-0.4.0/README.md +329 -0
- flexible_graphrag_mcp-0.4.0/flexible_graphrag_mcp.egg-info/PKG-INFO +345 -0
- flexible_graphrag_mcp-0.4.0/flexible_graphrag_mcp.egg-info/SOURCES.txt +9 -0
- flexible_graphrag_mcp-0.4.0/flexible_graphrag_mcp.egg-info/dependency_links.txt +1 -0
- flexible_graphrag_mcp-0.4.0/flexible_graphrag_mcp.egg-info/entry_points.txt +2 -0
- flexible_graphrag_mcp-0.4.0/flexible_graphrag_mcp.egg-info/requires.txt +9 -0
- flexible_graphrag_mcp-0.4.0/flexible_graphrag_mcp.egg-info/top_level.txt +1 -0
- flexible_graphrag_mcp-0.4.0/main.py +326 -0
- flexible_graphrag_mcp-0.4.0/pyproject.toml +32 -0
- flexible_graphrag_mcp-0.4.0/setup.cfg +4 -0
|
@@ -0,0 +1,345 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: flexible-graphrag-mcp
|
|
3
|
+
Version: 0.4.0
|
|
4
|
+
Summary: MCP Server for Flexible GraphRAG
|
|
5
|
+
Author: Steve Reiner
|
|
6
|
+
License-Expression: Apache-2.0
|
|
7
|
+
Description-Content-Type: text/markdown
|
|
8
|
+
Requires-Dist: fastmcp
|
|
9
|
+
Requires-Dist: nest-asyncio
|
|
10
|
+
Requires-Dist: httpx
|
|
11
|
+
Requires-Dist: python-dotenv
|
|
12
|
+
Provides-Extra: dev
|
|
13
|
+
Requires-Dist: pytest; extra == "dev"
|
|
14
|
+
Requires-Dist: black; extra == "dev"
|
|
15
|
+
Requires-Dist: flake8; extra == "dev"
|
|
16
|
+
|
|
17
|
+
# Flexible GraphRAG MCP Server
|
|
18
|
+
|
|
19
|
+
Model Context Protocol (MCP) server for Flexible GraphRAG system with optimized configurations for Claude Desktop and MCP Inspector.
|
|
20
|
+
|
|
21
|
+
## Quick Start
|
|
22
|
+
|
|
23
|
+
### 1. Choose Your Platform & Method
|
|
24
|
+
|
|
25
|
+
| Platform | Recommended | Alternative | Why |
|
|
26
|
+
|----------|-------------|-------------|-----|
|
|
27
|
+
| **Windows** | `pipx` | `uvx` | Clean system install vs. no install needed |
|
|
28
|
+
| **macOS** | `pipx` | `uvx` | Clean system install vs. no install needed |
|
|
29
|
+
|
|
30
|
+
### 2. Install
|
|
31
|
+
|
|
32
|
+
#### pipx (Recommended)
|
|
33
|
+
```bash
|
|
34
|
+
cd flexible-graphrag-mcp
|
|
35
|
+
pipx install .
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
#### uvx (No installation)
|
|
39
|
+
```bash
|
|
40
|
+
# Auto-installs when first used
|
|
41
|
+
uvx flexible-graphrag-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### 3. Configure Claude Desktop
|
|
45
|
+
|
|
46
|
+
Copy the appropriate config file to your Claude Desktop configuration:
|
|
47
|
+
|
|
48
|
+
#### Windows
|
|
49
|
+
- **Config location**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
50
|
+
- **pipx**: Use `claude-desktop-configs/windows/pipx-config.json`
|
|
51
|
+
- **uvx**: Use `claude-desktop-configs/windows/uvx-config.json`
|
|
52
|
+
|
|
53
|
+
#### macOS
|
|
54
|
+
- **Config location**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
55
|
+
- **pipx**: Use `claude-desktop-configs/macos/pipx-config.json`
|
|
56
|
+
- **uvx**: Use `claude-desktop-configs/macos/uvx-config.json`
|
|
57
|
+
|
|
58
|
+
### 4. Test Installation
|
|
59
|
+
|
|
60
|
+
Restart Claude Desktop and test:
|
|
61
|
+
```
|
|
62
|
+
@flexible-graphrag Check system status
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
## Configuration Files
|
|
66
|
+
|
|
67
|
+
### Claude Desktop Configs
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
claude-desktop-configs/
|
|
71
|
+
├── windows/
|
|
72
|
+
│ ├── pipx-config.json # Windows + pipx
|
|
73
|
+
│ └── uvx-config.json # Windows + uvx
|
|
74
|
+
└── macos/
|
|
75
|
+
├── pipx-config.json # macOS + pipx
|
|
76
|
+
└── uvx-config.json # macOS + uvx
|
|
77
|
+
|
|
78
|
+
mcp-inspector/
|
|
79
|
+
├── pipx-stdio-config.json # MCP Inspector + pipx (stdio - try first)
|
|
80
|
+
├── pipx-http-config.json # MCP Inspector + pipx (HTTP - fallback)
|
|
81
|
+
├── uvx-stdio-config.json # MCP Inspector + uvx (stdio - try first)
|
|
82
|
+
└── uvx-http-config.json # MCP Inspector + uvx (HTTP - fallback)
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Key Differences
|
|
86
|
+
|
|
87
|
+
#### Windows Configs
|
|
88
|
+
- Include Unicode environment variables (`PYTHONIOENCODING`, `PYTHONLEGACYWINDOWSSTDIO`)
|
|
89
|
+
- Prevent Unicode encoding errors with emojis and special characters
|
|
90
|
+
|
|
91
|
+
#### macOS Configs
|
|
92
|
+
- Clean and simple - no special environment variables needed
|
|
93
|
+
- Standard MCP protocol over stdio
|
|
94
|
+
|
|
95
|
+
#### MCP Inspector Configs
|
|
96
|
+
- **stdio configs**: Standard MCP protocol - try these first
|
|
97
|
+
- **http configs**: HTTP transport fallback if stdio has issues (like proxy problems)
|
|
98
|
+
- HTTP mode runs on port 3001 by default (configurable with `--port` argument)
|
|
99
|
+
- Platform-independent - works on Windows, macOS, and Linux
|
|
100
|
+
|
|
101
|
+
## Installation Methods
|
|
102
|
+
|
|
103
|
+
### pipx (Recommended)
|
|
104
|
+
|
|
105
|
+
**Advantages:**
|
|
106
|
+
- ✅ Clean system-level installation
|
|
107
|
+
- ✅ Isolated dependencies
|
|
108
|
+
- ✅ Simple `flexible-graphrag-mcp` command
|
|
109
|
+
- ✅ Automatic PATH management
|
|
110
|
+
|
|
111
|
+
**Installation:**
|
|
112
|
+
```bash
|
|
113
|
+
cd flexible-graphrag-mcp
|
|
114
|
+
pipx install .
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
**Update:**
|
|
118
|
+
```bash
|
|
119
|
+
pipx reinstall flexible-graphrag-mcp
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
### uvx (Alternative)
|
|
123
|
+
|
|
124
|
+
**Advantages:**
|
|
125
|
+
- ✅ No installation required
|
|
126
|
+
- ✅ Automatic dependency management
|
|
127
|
+
- ✅ Always runs latest version
|
|
128
|
+
- ✅ Great for testing
|
|
129
|
+
|
|
130
|
+
**Usage:**
|
|
131
|
+
```bash
|
|
132
|
+
uvx flexible-graphrag-mcp
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
## Prerequisites
|
|
136
|
+
|
|
137
|
+
### Backend Server Required
|
|
138
|
+
The MCP server communicates with the FastAPI backend, so you must have it running:
|
|
139
|
+
|
|
140
|
+
```bash
|
|
141
|
+
cd flexible-graphrag
|
|
142
|
+
uv run uvicorn main:app --host 0.0.0.0 --port 8000
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
### Environment Configuration
|
|
146
|
+
Ensure your `.env` file is properly configured in the main project directory:
|
|
147
|
+
|
|
148
|
+
```env
|
|
149
|
+
# Neo4j Configuration
|
|
150
|
+
NEO4J_URI=bolt://localhost:7687
|
|
151
|
+
NEO4J_USERNAME=neo4j
|
|
152
|
+
NEO4J_PASSWORD=your-password
|
|
153
|
+
NEO4J_DATABASE=neo4j
|
|
154
|
+
|
|
155
|
+
# LLM Configuration
|
|
156
|
+
OPENAI_API_KEY=your-key
|
|
157
|
+
LLM_PROVIDER=openai
|
|
158
|
+
EMBEDDING_PROVIDER=openai
|
|
159
|
+
```
|
|
160
|
+
|
|
161
|
+
## HTTP Mode for MCP Inspector
|
|
162
|
+
|
|
163
|
+
For debugging with MCP Inspector, the server supports HTTP transport:
|
|
164
|
+
|
|
165
|
+
```bash
|
|
166
|
+
# Using pipx
|
|
167
|
+
flexible-graphrag-mcp --http --port 3001
|
|
168
|
+
|
|
169
|
+
# Using uvx
|
|
170
|
+
uvx flexible-graphrag-mcp --http --port 3001
|
|
171
|
+
|
|
172
|
+
# Custom port
|
|
173
|
+
flexible-graphrag-mcp --http --port 8080
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
The HTTP mode is automatically configured in the `mcp-inspector/` config files and works better than stdio for debugging complex MCP interactions.
|
|
177
|
+
|
|
178
|
+
## Available Tools
|
|
179
|
+
|
|
180
|
+
- **`get_system_status()`** - System status and configuration
|
|
181
|
+
- **`ingest_documents()`** - Ingest documents from 13 data sources (all support `skip_graph`; filesystem/Alfresco/CMIS use `paths`; Alfresco also supports `nodeDetails` list)
|
|
182
|
+
- **`ingest_text(content, source_name)`** - Ingest custom text content
|
|
183
|
+
- **`search_documents(query, top_k)`** - Hybrid search for document retrieval
|
|
184
|
+
- **`query_documents(query, top_k)`** - AI-generated answers from documents
|
|
185
|
+
- **`test_with_sample()`** - Quick test with sample text
|
|
186
|
+
- **`check_processing_status(processing_id)`** - Check async operation status
|
|
187
|
+
- **`get_python_info()`** - Python environment information
|
|
188
|
+
- **`health_check()`** - Backend connectivity check
|
|
189
|
+
|
|
190
|
+
## Tool Details
|
|
191
|
+
|
|
192
|
+
### `ingest_documents`
|
|
193
|
+
Ingest documents from various sources into the knowledge graph.
|
|
194
|
+
|
|
195
|
+
**Parameters:**
|
|
196
|
+
- `data_source` (string, default: "filesystem"): Type of data source
|
|
197
|
+
- Options: `filesystem`, `cmis`, `alfresco`, `web`, `wikipedia`, `youtube`, `s3`, `gcs`, `azure_blob`, `onedrive`, `sharepoint`, `box`, `google_drive`
|
|
198
|
+
- `paths` (string, optional): File path(s) to process (for filesystem, Alfresco, and CMIS sources)
|
|
199
|
+
- Single path: `"/path/to/file.pdf"`
|
|
200
|
+
- Multiple paths (JSON array): `["file1.pdf", "file2.docx"]`
|
|
201
|
+
- `skip_graph` (boolean, default: false): Skip knowledge graph extraction on a per-ingest basis for faster performance (vector + search only)
|
|
202
|
+
- `cmis_config` (string, optional): CMIS configuration as JSON string
|
|
203
|
+
- `alfresco_config` (string, optional): Alfresco configuration as JSON string (also supports `nodeDetails` list for multi-select)
|
|
204
|
+
- `web_config` (string, optional): Web page configuration as JSON string
|
|
205
|
+
- `wikipedia_config` (string, optional): Wikipedia configuration as JSON string
|
|
206
|
+
- `youtube_config` (string, optional): YouTube configuration as JSON string
|
|
207
|
+
- `s3_config` (string, optional): Amazon S3 configuration as JSON string
|
|
208
|
+
- `gcs_config` (string, optional): Google Cloud Storage configuration as JSON string
|
|
209
|
+
- `azure_blob_config` (string, optional): Azure Blob Storage configuration as JSON string
|
|
210
|
+
- `onedrive_config` (string, optional): Microsoft OneDrive configuration as JSON string
|
|
211
|
+
- `sharepoint_config` (string, optional): Microsoft SharePoint configuration as JSON string
|
|
212
|
+
- `box_config` (string, optional): Box configuration as JSON string
|
|
213
|
+
- `google_drive_config` (string, optional): Google Drive configuration as JSON string
|
|
214
|
+
|
|
215
|
+
**Example - Basic filesystem with skip_graph:**
|
|
216
|
+
```json
|
|
217
|
+
{
|
|
218
|
+
"data_source": "filesystem",
|
|
219
|
+
"paths": "[\"./sample-docs/cmispress.txt\", \"./sample-docs/space-station.txt\"]",
|
|
220
|
+
"skip_graph": true
|
|
221
|
+
}
|
|
222
|
+
```
|
|
223
|
+
|
|
224
|
+
**Example - CMIS with single path:**
|
|
225
|
+
```json
|
|
226
|
+
{
|
|
227
|
+
"data_source": "cmis",
|
|
228
|
+
"paths": "[\"/Shared/GraphRAG/cmispress.txt\"]",
|
|
229
|
+
"cmis_config": "{\"url\": \"https://cmis.example.com\", \"username\": \"admin\", \"password\": \"password\", \"folder_path\": \"/Shared/GraphRAG\"}"
|
|
230
|
+
}
|
|
231
|
+
```
|
|
232
|
+
|
|
233
|
+
**Example - Alfresco with single path:**
|
|
234
|
+
```json
|
|
235
|
+
{
|
|
236
|
+
"data_source": "alfresco",
|
|
237
|
+
"paths": "[\"/Shared/GraphRAG/space-station.txt\"]",
|
|
238
|
+
"alfresco_config": "{\"url\": \"https://alfresco.example.com\", \"username\": \"admin\", \"password\": \"password\", \"path\": \"/Shared/GraphRAG\"}"
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
**Example - Alfresco with nodeDetails (multi-select from ACA):**
|
|
243
|
+
```json
|
|
244
|
+
{
|
|
245
|
+
"data_source": "alfresco",
|
|
246
|
+
"alfresco_config": "{\"url\": \"https://alfresco.example.com\", \"username\": \"admin\", \"password\": \"password\", \"nodeDetails\": [{\"id\": \"abc123\", \"name\": \"doc1.pdf\", \"path\": \"/Shared/GraphRAG/doc1.pdf\", \"isFile\": true, \"isFolder\": false}], \"recursive\": false}"
|
|
247
|
+
}
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
**Example - Amazon S3:**
|
|
251
|
+
```json
|
|
252
|
+
{
|
|
253
|
+
"data_source": "s3",
|
|
254
|
+
"s3_config": "{\"bucket_name\": \"my-bucket\", \"prefix\": \"documents/\", \"access_key\": \"AKIAIOSFODNN7EXAMPLE\", \"secret_key\": \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\", \"region_name\": \"us-east-1\"}"
|
|
255
|
+
}
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
## Example Usage
|
|
259
|
+
|
|
260
|
+
### Basic Document Ingestion
|
|
261
|
+
```
|
|
262
|
+
@flexible-graphrag Please ingest documents from C:/Documents/research
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
### Fast Ingestion (Skip Graph)
|
|
266
|
+
```
|
|
267
|
+
@flexible-graphrag Ingest from ./sample-docs/ with skip_graph=true for faster processing (works with all data sources)
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Alfresco Multi-Select
|
|
271
|
+
```
|
|
272
|
+
@flexible-graphrag Ingest from Alfresco with this config: {"url": "https://alfresco.example.com", "username": "admin", "password": "password", "nodeDetails": [{"id": "abc123", "name": "report.pdf", "path": "/Shared/Reports/report.pdf", "isFile": true, "isFolder": false}]}
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
### Custom Text Processing
|
|
276
|
+
```
|
|
277
|
+
@flexible-graphrag Ingest this text: "Claude is an AI assistant created by Anthropic."
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
### Search and Q&A
|
|
281
|
+
```
|
|
282
|
+
@flexible-graphrag Search for "machine learning algorithms" in the documents
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
```
|
|
286
|
+
@flexible-graphrag What are the main conclusions from the research papers?
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
### Async Processing
|
|
290
|
+
```
|
|
291
|
+
@flexible-graphrag Check processing status for ID abc123
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
## Troubleshooting
|
|
295
|
+
|
|
296
|
+
### Common Issues
|
|
297
|
+
|
|
298
|
+
#### pipx Command Not Found
|
|
299
|
+
```bash
|
|
300
|
+
# Install pipx
|
|
301
|
+
python -m pip install --user pipx
|
|
302
|
+
pipx ensurepath
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
#### uvx Command Not Found
|
|
306
|
+
```bash
|
|
307
|
+
# Install uvx via uv
|
|
308
|
+
uv tool install uvx
|
|
309
|
+
```
|
|
310
|
+
|
|
311
|
+
#### Unicode Errors on Windows
|
|
312
|
+
- Windows configs include required environment variables automatically
|
|
313
|
+
- If issues persist, check that you're using the correct Windows config file
|
|
314
|
+
|
|
315
|
+
#### Backend Connection Error
|
|
316
|
+
- Ensure FastAPI backend is running on `localhost:8000`
|
|
317
|
+
- Check that `.env` file is properly configured
|
|
318
|
+
- Test backend directly: `curl http://localhost:8000/api/health`
|
|
319
|
+
|
|
320
|
+
#### Claude Desktop Not Recognizing Server
|
|
321
|
+
- Restart Claude Desktop after config changes
|
|
322
|
+
- Check config file path and JSON syntax
|
|
323
|
+
- Verify command exists: run `flexible-graphrag-mcp` or `uvx flexible-graphrag-mcp` in terminal
|
|
324
|
+
|
|
325
|
+
## Development
|
|
326
|
+
|
|
327
|
+
### Test Scripts
|
|
328
|
+
```bash
|
|
329
|
+
# Windows
|
|
330
|
+
.\test-installation.ps1
|
|
331
|
+
|
|
332
|
+
# macOS/Linux
|
|
333
|
+
./test-installation.sh
|
|
334
|
+
```
|
|
335
|
+
|
|
336
|
+
These scripts test both installation methods and help verify everything works correctly.
|
|
337
|
+
|
|
338
|
+
### Adding New Tools
|
|
339
|
+
1. Add tool function to `main.py` with `@mcp.tool()` decorator
|
|
340
|
+
2. Update tool list in README
|
|
341
|
+
3. Test with MCP Inspector for debugging
|
|
342
|
+
|
|
343
|
+
## MCP Inspector Integration
|
|
344
|
+
|
|
345
|
+
Use the configs in `mcp-inspector/` directory for debugging with the MCP Inspector tool. These work with both pipx and uvx installations and are platform-independent.
|
|
@@ -0,0 +1,329 @@
|
|
|
1
|
+
# Flexible GraphRAG MCP Server
|
|
2
|
+
|
|
3
|
+
Model Context Protocol (MCP) server for Flexible GraphRAG system with optimized configurations for Claude Desktop and MCP Inspector.
|
|
4
|
+
|
|
5
|
+
## Quick Start
|
|
6
|
+
|
|
7
|
+
### 1. Choose Your Platform & Method
|
|
8
|
+
|
|
9
|
+
| Platform | Recommended | Alternative | Why |
|
|
10
|
+
|----------|-------------|-------------|-----|
|
|
11
|
+
| **Windows** | `pipx` | `uvx` | Clean system install vs. no install needed |
|
|
12
|
+
| **macOS** | `pipx` | `uvx` | Clean system install vs. no install needed |
|
|
13
|
+
|
|
14
|
+
### 2. Install
|
|
15
|
+
|
|
16
|
+
#### pipx (Recommended)
|
|
17
|
+
```bash
|
|
18
|
+
cd flexible-graphrag-mcp
|
|
19
|
+
pipx install .
|
|
20
|
+
```
|
|
21
|
+
|
|
22
|
+
#### uvx (No installation)
|
|
23
|
+
```bash
|
|
24
|
+
# Auto-installs when first used
|
|
25
|
+
uvx flexible-graphrag-mcp
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
### 3. Configure Claude Desktop
|
|
29
|
+
|
|
30
|
+
Copy the appropriate config file to your Claude Desktop configuration:
|
|
31
|
+
|
|
32
|
+
#### Windows
|
|
33
|
+
- **Config location**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
34
|
+
- **pipx**: Use `claude-desktop-configs/windows/pipx-config.json`
|
|
35
|
+
- **uvx**: Use `claude-desktop-configs/windows/uvx-config.json`
|
|
36
|
+
|
|
37
|
+
#### macOS
|
|
38
|
+
- **Config location**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
39
|
+
- **pipx**: Use `claude-desktop-configs/macos/pipx-config.json`
|
|
40
|
+
- **uvx**: Use `claude-desktop-configs/macos/uvx-config.json`
|
|
41
|
+
|
|
42
|
+
### 4. Test Installation
|
|
43
|
+
|
|
44
|
+
Restart Claude Desktop and test:
|
|
45
|
+
```
|
|
46
|
+
@flexible-graphrag Check system status
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Configuration Files
|
|
50
|
+
|
|
51
|
+
### Claude Desktop Configs
|
|
52
|
+
|
|
53
|
+
```
|
|
54
|
+
claude-desktop-configs/
|
|
55
|
+
├── windows/
|
|
56
|
+
│ ├── pipx-config.json # Windows + pipx
|
|
57
|
+
│ └── uvx-config.json # Windows + uvx
|
|
58
|
+
└── macos/
|
|
59
|
+
├── pipx-config.json # macOS + pipx
|
|
60
|
+
└── uvx-config.json # macOS + uvx
|
|
61
|
+
|
|
62
|
+
mcp-inspector/
|
|
63
|
+
├── pipx-stdio-config.json # MCP Inspector + pipx (stdio - try first)
|
|
64
|
+
├── pipx-http-config.json # MCP Inspector + pipx (HTTP - fallback)
|
|
65
|
+
├── uvx-stdio-config.json # MCP Inspector + uvx (stdio - try first)
|
|
66
|
+
└── uvx-http-config.json # MCP Inspector + uvx (HTTP - fallback)
|
|
67
|
+
```
|
|
68
|
+
|
|
69
|
+
### Key Differences
|
|
70
|
+
|
|
71
|
+
#### Windows Configs
|
|
72
|
+
- Include Unicode environment variables (`PYTHONIOENCODING`, `PYTHONLEGACYWINDOWSSTDIO`)
|
|
73
|
+
- Prevent Unicode encoding errors with emojis and special characters
|
|
74
|
+
|
|
75
|
+
#### macOS Configs
|
|
76
|
+
- Clean and simple - no special environment variables needed
|
|
77
|
+
- Standard MCP protocol over stdio
|
|
78
|
+
|
|
79
|
+
#### MCP Inspector Configs
|
|
80
|
+
- **stdio configs**: Standard MCP protocol - try these first
|
|
81
|
+
- **http configs**: HTTP transport fallback if stdio has issues (like proxy problems)
|
|
82
|
+
- HTTP mode runs on port 3001 by default (configurable with `--port` argument)
|
|
83
|
+
- Platform-independent - works on Windows, macOS, and Linux
|
|
84
|
+
|
|
85
|
+
## Installation Methods
|
|
86
|
+
|
|
87
|
+
### pipx (Recommended)
|
|
88
|
+
|
|
89
|
+
**Advantages:**
|
|
90
|
+
- ✅ Clean system-level installation
|
|
91
|
+
- ✅ Isolated dependencies
|
|
92
|
+
- ✅ Simple `flexible-graphrag-mcp` command
|
|
93
|
+
- ✅ Automatic PATH management
|
|
94
|
+
|
|
95
|
+
**Installation:**
|
|
96
|
+
```bash
|
|
97
|
+
cd flexible-graphrag-mcp
|
|
98
|
+
pipx install .
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**Update:**
|
|
102
|
+
```bash
|
|
103
|
+
pipx reinstall flexible-graphrag-mcp
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
### uvx (Alternative)
|
|
107
|
+
|
|
108
|
+
**Advantages:**
|
|
109
|
+
- ✅ No installation required
|
|
110
|
+
- ✅ Automatic dependency management
|
|
111
|
+
- ✅ Always runs latest version
|
|
112
|
+
- ✅ Great for testing
|
|
113
|
+
|
|
114
|
+
**Usage:**
|
|
115
|
+
```bash
|
|
116
|
+
uvx flexible-graphrag-mcp
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
## Prerequisites
|
|
120
|
+
|
|
121
|
+
### Backend Server Required
|
|
122
|
+
The MCP server communicates with the FastAPI backend, so you must have it running:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
cd flexible-graphrag
|
|
126
|
+
uv run uvicorn main:app --host 0.0.0.0 --port 8000
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
### Environment Configuration
|
|
130
|
+
Ensure your `.env` file is properly configured in the main project directory:
|
|
131
|
+
|
|
132
|
+
```env
|
|
133
|
+
# Neo4j Configuration
|
|
134
|
+
NEO4J_URI=bolt://localhost:7687
|
|
135
|
+
NEO4J_USERNAME=neo4j
|
|
136
|
+
NEO4J_PASSWORD=your-password
|
|
137
|
+
NEO4J_DATABASE=neo4j
|
|
138
|
+
|
|
139
|
+
# LLM Configuration
|
|
140
|
+
OPENAI_API_KEY=your-key
|
|
141
|
+
LLM_PROVIDER=openai
|
|
142
|
+
EMBEDDING_PROVIDER=openai
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## HTTP Mode for MCP Inspector
|
|
146
|
+
|
|
147
|
+
For debugging with MCP Inspector, the server supports HTTP transport:
|
|
148
|
+
|
|
149
|
+
```bash
|
|
150
|
+
# Using pipx
|
|
151
|
+
flexible-graphrag-mcp --http --port 3001
|
|
152
|
+
|
|
153
|
+
# Using uvx
|
|
154
|
+
uvx flexible-graphrag-mcp --http --port 3001
|
|
155
|
+
|
|
156
|
+
# Custom port
|
|
157
|
+
flexible-graphrag-mcp --http --port 8080
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
The HTTP mode is automatically configured in the `mcp-inspector/` config files and works better than stdio for debugging complex MCP interactions.
|
|
161
|
+
|
|
162
|
+
## Available Tools
|
|
163
|
+
|
|
164
|
+
- **`get_system_status()`** - System status and configuration
|
|
165
|
+
- **`ingest_documents()`** - Ingest documents from 13 data sources (all support `skip_graph`; filesystem/Alfresco/CMIS use `paths`; Alfresco also supports `nodeDetails` list)
|
|
166
|
+
- **`ingest_text(content, source_name)`** - Ingest custom text content
|
|
167
|
+
- **`search_documents(query, top_k)`** - Hybrid search for document retrieval
|
|
168
|
+
- **`query_documents(query, top_k)`** - AI-generated answers from documents
|
|
169
|
+
- **`test_with_sample()`** - Quick test with sample text
|
|
170
|
+
- **`check_processing_status(processing_id)`** - Check async operation status
|
|
171
|
+
- **`get_python_info()`** - Python environment information
|
|
172
|
+
- **`health_check()`** - Backend connectivity check
|
|
173
|
+
|
|
174
|
+
## Tool Details
|
|
175
|
+
|
|
176
|
+
### `ingest_documents`
|
|
177
|
+
Ingest documents from various sources into the knowledge graph.
|
|
178
|
+
|
|
179
|
+
**Parameters:**
|
|
180
|
+
- `data_source` (string, default: "filesystem"): Type of data source
|
|
181
|
+
- Options: `filesystem`, `cmis`, `alfresco`, `web`, `wikipedia`, `youtube`, `s3`, `gcs`, `azure_blob`, `onedrive`, `sharepoint`, `box`, `google_drive`
|
|
182
|
+
- `paths` (string, optional): File path(s) to process (for filesystem, Alfresco, and CMIS sources)
|
|
183
|
+
- Single path: `"/path/to/file.pdf"`
|
|
184
|
+
- Multiple paths (JSON array): `["file1.pdf", "file2.docx"]`
|
|
185
|
+
- `skip_graph` (boolean, default: false): Skip knowledge graph extraction on a per-ingest basis for faster performance (vector + search only)
|
|
186
|
+
- `cmis_config` (string, optional): CMIS configuration as JSON string
|
|
187
|
+
- `alfresco_config` (string, optional): Alfresco configuration as JSON string (also supports `nodeDetails` list for multi-select)
|
|
188
|
+
- `web_config` (string, optional): Web page configuration as JSON string
|
|
189
|
+
- `wikipedia_config` (string, optional): Wikipedia configuration as JSON string
|
|
190
|
+
- `youtube_config` (string, optional): YouTube configuration as JSON string
|
|
191
|
+
- `s3_config` (string, optional): Amazon S3 configuration as JSON string
|
|
192
|
+
- `gcs_config` (string, optional): Google Cloud Storage configuration as JSON string
|
|
193
|
+
- `azure_blob_config` (string, optional): Azure Blob Storage configuration as JSON string
|
|
194
|
+
- `onedrive_config` (string, optional): Microsoft OneDrive configuration as JSON string
|
|
195
|
+
- `sharepoint_config` (string, optional): Microsoft SharePoint configuration as JSON string
|
|
196
|
+
- `box_config` (string, optional): Box configuration as JSON string
|
|
197
|
+
- `google_drive_config` (string, optional): Google Drive configuration as JSON string
|
|
198
|
+
|
|
199
|
+
**Example - Basic filesystem with skip_graph:**
|
|
200
|
+
```json
|
|
201
|
+
{
|
|
202
|
+
"data_source": "filesystem",
|
|
203
|
+
"paths": "[\"./sample-docs/cmispress.txt\", \"./sample-docs/space-station.txt\"]",
|
|
204
|
+
"skip_graph": true
|
|
205
|
+
}
|
|
206
|
+
```
|
|
207
|
+
|
|
208
|
+
**Example - CMIS with single path:**
|
|
209
|
+
```json
|
|
210
|
+
{
|
|
211
|
+
"data_source": "cmis",
|
|
212
|
+
"paths": "[\"/Shared/GraphRAG/cmispress.txt\"]",
|
|
213
|
+
"cmis_config": "{\"url\": \"https://cmis.example.com\", \"username\": \"admin\", \"password\": \"password\", \"folder_path\": \"/Shared/GraphRAG\"}"
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
**Example - Alfresco with single path:**
|
|
218
|
+
```json
|
|
219
|
+
{
|
|
220
|
+
"data_source": "alfresco",
|
|
221
|
+
"paths": "[\"/Shared/GraphRAG/space-station.txt\"]",
|
|
222
|
+
"alfresco_config": "{\"url\": \"https://alfresco.example.com\", \"username\": \"admin\", \"password\": \"password\", \"path\": \"/Shared/GraphRAG\"}"
|
|
223
|
+
}
|
|
224
|
+
```
|
|
225
|
+
|
|
226
|
+
**Example - Alfresco with nodeDetails (multi-select from ACA):**
|
|
227
|
+
```json
|
|
228
|
+
{
|
|
229
|
+
"data_source": "alfresco",
|
|
230
|
+
"alfresco_config": "{\"url\": \"https://alfresco.example.com\", \"username\": \"admin\", \"password\": \"password\", \"nodeDetails\": [{\"id\": \"abc123\", \"name\": \"doc1.pdf\", \"path\": \"/Shared/GraphRAG/doc1.pdf\", \"isFile\": true, \"isFolder\": false}], \"recursive\": false}"
|
|
231
|
+
}
|
|
232
|
+
```
|
|
233
|
+
|
|
234
|
+
**Example - Amazon S3:**
|
|
235
|
+
```json
|
|
236
|
+
{
|
|
237
|
+
"data_source": "s3",
|
|
238
|
+
"s3_config": "{\"bucket_name\": \"my-bucket\", \"prefix\": \"documents/\", \"access_key\": \"AKIAIOSFODNN7EXAMPLE\", \"secret_key\": \"wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY\", \"region_name\": \"us-east-1\"}"
|
|
239
|
+
}
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
## Example Usage
|
|
243
|
+
|
|
244
|
+
### Basic Document Ingestion
|
|
245
|
+
```
|
|
246
|
+
@flexible-graphrag Please ingest documents from C:/Documents/research
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
### Fast Ingestion (Skip Graph)
|
|
250
|
+
```
|
|
251
|
+
@flexible-graphrag Ingest from ./sample-docs/ with skip_graph=true for faster processing (works with all data sources)
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
### Alfresco Multi-Select
|
|
255
|
+
```
|
|
256
|
+
@flexible-graphrag Ingest from Alfresco with this config: {"url": "https://alfresco.example.com", "username": "admin", "password": "password", "nodeDetails": [{"id": "abc123", "name": "report.pdf", "path": "/Shared/Reports/report.pdf", "isFile": true, "isFolder": false}]}
|
|
257
|
+
```
|
|
258
|
+
|
|
259
|
+
### Custom Text Processing
|
|
260
|
+
```
|
|
261
|
+
@flexible-graphrag Ingest this text: "Claude is an AI assistant created by Anthropic."
|
|
262
|
+
```
|
|
263
|
+
|
|
264
|
+
### Search and Q&A
|
|
265
|
+
```
|
|
266
|
+
@flexible-graphrag Search for "machine learning algorithms" in the documents
|
|
267
|
+
```
|
|
268
|
+
|
|
269
|
+
```
|
|
270
|
+
@flexible-graphrag What are the main conclusions from the research papers?
|
|
271
|
+
```
|
|
272
|
+
|
|
273
|
+
### Async Processing
|
|
274
|
+
```
|
|
275
|
+
@flexible-graphrag Check processing status for ID abc123
|
|
276
|
+
```
|
|
277
|
+
|
|
278
|
+
## Troubleshooting
|
|
279
|
+
|
|
280
|
+
### Common Issues
|
|
281
|
+
|
|
282
|
+
#### pipx Command Not Found
|
|
283
|
+
```bash
|
|
284
|
+
# Install pipx
|
|
285
|
+
python -m pip install --user pipx
|
|
286
|
+
pipx ensurepath
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
#### uvx Command Not Found
|
|
290
|
+
```bash
|
|
291
|
+
# Install uvx via uv
|
|
292
|
+
uv tool install uvx
|
|
293
|
+
```
|
|
294
|
+
|
|
295
|
+
#### Unicode Errors on Windows
|
|
296
|
+
- Windows configs include required environment variables automatically
|
|
297
|
+
- If issues persist, check that you're using the correct Windows config file
|
|
298
|
+
|
|
299
|
+
#### Backend Connection Error
|
|
300
|
+
- Ensure FastAPI backend is running on `localhost:8000`
|
|
301
|
+
- Check that `.env` file is properly configured
|
|
302
|
+
- Test backend directly: `curl http://localhost:8000/api/health`
|
|
303
|
+
|
|
304
|
+
#### Claude Desktop Not Recognizing Server
|
|
305
|
+
- Restart Claude Desktop after config changes
|
|
306
|
+
- Check config file path and JSON syntax
|
|
307
|
+
- Verify command exists: run `flexible-graphrag-mcp` or `uvx flexible-graphrag-mcp` in terminal
|
|
308
|
+
|
|
309
|
+
## Development
|
|
310
|
+
|
|
311
|
+
### Test Scripts
|
|
312
|
+
```bash
|
|
313
|
+
# Windows
|
|
314
|
+
.\test-installation.ps1
|
|
315
|
+
|
|
316
|
+
# macOS/Linux
|
|
317
|
+
./test-installation.sh
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
These scripts test both installation methods and help verify everything works correctly.
|
|
321
|
+
|
|
322
|
+
### Adding New Tools
|
|
323
|
+
1. Add tool function to `main.py` with `@mcp.tool()` decorator
|
|
324
|
+
2. Update tool list in README
|
|
325
|
+
3. Test with MCP Inspector for debugging
|
|
326
|
+
|
|
327
|
+
## MCP Inspector Integration
|
|
328
|
+
|
|
329
|
+
Use the configs in `mcp-inspector/` directory for debugging with the MCP Inspector tool. These work with both pipx and uvx installations and are platform-independent.
|