Skip to content

Commit b1a785d

Browse files
authored
docs: add Smithery badge to README (#19)
1 parent 0ecd73f commit b1a785d

1 file changed

Lines changed: 3 additions & 289 deletions

File tree

README.md

Lines changed: 3 additions & 289 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
# WisdomForge
22

3+
[![smithery badge](https://smithery.ai/badge/@hadv/wisdomforge)](https://smithery.ai/server/@hadv/wisdomforge)
4+
35
A powerful knowledge management system that forges wisdom from experiences, insights, and best practices. Built with Qdrant vector database for efficient knowledge storage and retrieval.
46

57
## Features
@@ -124,292 +126,4 @@ Add this configuration in Claude's settings:
124126
}
125127
]
126128
}
127-
```
128-
129-
## Deployment Options
130-
131-
### Option 1: Local Deployment
132-
Run the MCP server on your local machine or your own infrastructure:
133-
134-
1. Configure your environment variables in `.env` file
135-
2. Build the project:
136-
```bash
137-
npm run build
138-
```
139-
3. Start the server:
140-
```bash
141-
npm start
142-
```
143-
144-
The server will run locally and be accessible at `http://localhost:3000` (or your configured PORT).
145-
146-
### Option 2: Smithery.ai Cloud Deployment
147-
Deploy the MCP server to Smithery's cloud infrastructure:
148-
149-
1. Create an account on [Smithery.ai](https://smithery.ai)
150-
2. Install the Smithery CLI:
151-
```bash
152-
npm install -g @smithery/cli
153-
```
154-
155-
3. Login to Smithery:
156-
```bash
157-
smithery login
158-
```
159-
160-
4. Create a new instance for your organization:
161-
```bash
162-
smithery create instance wisdomforge
163-
```
164-
165-
5. Configure your environment variables in Smithery dashboard for your instance:
166-
- `DATABASE_TYPE` (default: "qdrant")
167-
- `COLLECTION_NAME` (required)
168-
- `HTTP_SERVER` (default: "true")
169-
- `QDRANT_URL` (required if using Qdrant)
170-
- `QDRANT_API_KEY` (required if using Qdrant)
171-
- `CHROMA_URL` (required if using Chroma)
172-
- Note: `PORT` is not needed for cloud deployment as Smithery handles networking
173-
174-
6. Deploy your server:
175-
```bash
176-
npm run deploy
177-
```
178-
179-
### Choosing Between Local and Cloud Deployment
180-
181-
#### Local Deployment is recommended when:
182-
- You need full control over the infrastructure
183-
- You have specific security requirements
184-
- You want to minimize costs
185-
- You need to run the server behind a firewall
186-
- You're in development or testing phase
187-
188-
#### Smithery Cloud Deployment is recommended when:
189-
- You want managed infrastructure
190-
- You need automatic scaling
191-
- You want to avoid server maintenance
192-
- You need high availability
193-
- You're in production environment
194-
195-
### Instance Management (Cloud Deployment)
196-
- Each organization/user needs their own Smithery.ai instance
197-
- Instances are isolated and have their own configuration
198-
- You can create multiple instances for different environments (dev, staging, prod)
199-
- Instance URLs follow the pattern: `https://<instance-name>.smithery.ai`
200-
201-
### Post-Deployment
202-
- Local: Server runs on your machine at `http://localhost:3000`
203-
- Cloud: Server runs on Smithery at `https://<instance-name>.smithery.ai`
204-
- Monitor your deployment in the Smithery dashboard (cloud only)
205-
- Use the health check endpoint at `/health` to verify server status
206-
207-
### Multi-User Setup
208-
For cloud deployment, if you need to share access with team members:
209-
1. Add team members to your Smithery.ai organization
210-
2. Grant them appropriate permissions for your instance
211-
3. Each team member can use the same instance URL but should configure their own:
212-
- Database credentials
213-
- Collection names
214-
- Other environment-specific settings
215-
216-
For local deployment:
217-
- Each user runs their own instance
218-
- Users need to configure their own environment variables
219-
- No shared access is possible unless you set up your own infrastructure
220-
221-
## MCP Client Connection
222-
223-
### Local Deployment Connection
224-
When running the server locally, MCP clients (like Cursor or Claude) can connect using the following configuration:
225-
226-
#### Cursor AI IDE
227-
Update your `~/.cursor/mcp.json` or `.cursor/mcp.json`:
228-
```json
229-
{
230-
"mcpServers": {
231-
"wisdomforge": {
232-
"url": "http://localhost:3000",
233-
"type": "http"
234-
}
235-
}
236-
}
237-
```
238-
239-
#### Claude Desktop
240-
Update your Claude settings:
241-
```json
242-
{
243-
"processes": {
244-
"knowledge_server": {
245-
"url": "http://localhost:3000",
246-
"type": "http"
247-
}
248-
},
249-
"tools": [
250-
{
251-
"name": "store_knowledge",
252-
"description": "Store domain-specific knowledge in a vector database",
253-
"provider": "http",
254-
"url": "http://localhost:3000"
255-
},
256-
{
257-
"name": "retrieve_knowledge_context",
258-
"description": "Retrieve relevant domain knowledge from a vector database",
259-
"provider": "http",
260-
"url": "http://localhost:3000"
261-
}
262-
]
263-
}
264-
```
265-
266-
### Connection Notes
267-
1. For local deployment:
268-
- No authentication required
269-
- Server must be running before clients can connect
270-
- Use `http://localhost:3000` or your configured PORT
271-
- HTTP server is enabled by default
272-
273-
2. For cloud deployment:
274-
- Authentication required via Smithery API key
275-
- Server is always available
276-
- Use `https://<instance-name>.smithery.ai`
277-
- HTTP server is enabled by default
278-
- Replace `<instance-name>` with your actual instance name
279-
- Replace `<your-smithery-api-key>` with your actual Smithery API key
280-
281-
3. Testing the Connection:
282-
- Use the health check endpoint: `GET /health`
283-
- Local: `http://localhost:3000/health`
284-
- Cloud: `https://<instance-name>.smithery.ai/health`
285-
286-
## Usage
287-
288-
### Starting the Server
289-
290-
```bash
291-
npm start
292-
```
293-
294-
For development with auto-reload:
295-
```bash
296-
npm run dev
297-
```
298-
299-
### Storing Documentation
300-
301-
The server includes a script to store documentation files (PDF and TXT) with metadata:
302-
303-
```bash
304-
npm run store-doc <path-to-your-file>
305-
```
306-
307-
Example:
308-
```bash
309-
# Store a PDF file
310-
npm run store-doc docs/manual.pdf
311-
312-
# Store a text file
313-
npm run store-doc docs/readme.txt
314-
```
315-
316-
The script will:
317-
- Extract content from the file (text from PDF or plain text)
318-
- Store the content with metadata including:
319-
- Source: "documentation"
320-
- File name and extension
321-
- File size
322-
- Last modified date
323-
- Creation date
324-
- Content type
325-
326-
### API Endpoints
327-
328-
#### Store Domain Knowledge
329-
330-
```http
331-
POST /api/store
332-
Content-Type: application/json
333-
334-
{
335-
"content": "Your domain knowledge content here",
336-
"source": "your-source",
337-
"metadata": {
338-
"key": "value"
339-
}
340-
}
341-
```
342-
343-
#### Query Domain Knowledge
344-
345-
```http
346-
POST /api/query
347-
Content-Type: application/json
348-
349-
{
350-
"query": "Your search query here",
351-
"limit": 5
352-
}
353-
```
354-
355-
## Development
356-
357-
### Running Tests
358-
359-
```bash
360-
npm test
361-
```
362-
363-
### Building the Project
364-
365-
```bash
366-
npm run build
367-
```
368-
369-
### Linting
370-
371-
```bash
372-
npm run lint
373-
```
374-
375-
376-
## Using with Remote Qdrant
377-
378-
When using with a remote Qdrant instance (like Qdrant Cloud):
379-
380-
1. Ensure your `.env` has the correct URL with port number:
381-
```
382-
QDRANT_URL=https://your-instance-id.region.gcp.cloud.qdrant.io:6333
383-
```
384-
385-
2. Set your API key:
386-
```
387-
QDRANT_API_KEY=your_qdrant_api_key
388-
```
389-
390-
## FastEmbed Integration
391-
392-
This project uses Qdrant's built-in FastEmbed for efficient embedding generation:
393-
394-
### Benefits
395-
- Lightweight and fast embedding generation
396-
- Uses quantized model weights and ONNX Runtime for inference
397-
- Better accuracy than OpenAI Ada-002 according to Qdrant
398-
- No need for external embedding API keys
399-
400-
### How It Works
401-
1. The system connects to your Qdrant instance
402-
2. When generating embeddings, it uses Qdrant's server-side embedding endpoint
403-
3. This eliminates the need for external embedding APIs and simplifies the architecture
404-
405-
### Configuration
406-
No additional configuration is needed as FastEmbed is built into Qdrant. Just ensure your Qdrant URL and API key are correctly set in your `.env` file.
407-
408-
## Troubleshooting
409-
410-
If you encounter issues:
411-
412-
1. Make sure you're using Node.js LTS version (`nvm use --lts`)
413-
2. Verify your environment variables are correct
414-
3. Check Qdrant/Chroma connectivity
415-
4. Ensure your Qdrant instance is properly configured
129+
```

0 commit comments

Comments
 (0)