didier
e700a81c25
Schema: public_id + version columns with UNIQUE constraint, delete_timestamp for soft-delete. Tools: store_flashcard accepts optional public_id, update_flashcard creates a new version preserving history, delete_flashcard inserts a tombstone row and removes the Qdrant point. Qdrant: point ID is public_id (only latest version indexed).
118 lines
2.7 KiB
Markdown
118 lines
2.7 KiB
Markdown
# St-Pierre - Flashcard MCP Server
|
|
|
|
Remote MCP server that stores and retrieves flashcards using Qdrant vector
|
|
database and OpenAI embeddings.
|
|
|
|
## Tools
|
|
|
|
### `store_flashcard`
|
|
Store a flashcard for later retrieval. Automatically generates
|
|
embeddings via OpenAI and persists them in Qdrant.
|
|
|
|
Parameters:
|
|
- `note` (string, required): The markdown body
|
|
- `repos` (array of string, optional): Repository names
|
|
- `host` (string, optional): Hostname or null if universal
|
|
- `tags` (array of string, optional): Tags
|
|
- `user` (string, optional): User identifier
|
|
- `context` (string, optional): What triggered this
|
|
|
|
### `search_flashcard`
|
|
Semantic search across stored flashcards.
|
|
|
|
Parameters:
|
|
- `query` (string, required): Search query
|
|
- `limit` (number, optional, default 5): Max results
|
|
|
|
## Setup
|
|
|
|
### Prerequisites
|
|
|
|
- Qdrant instance
|
|
- OpenAI API key
|
|
|
|
### Environment Variables
|
|
|
|
```env
|
|
QDRANT_URL=localhost # Required: Qdrant hostname
|
|
QDRANT_PORT=6334 # Optional: Qdrant gRPC port (default: 6334)
|
|
QDRANT_API_KEY= # Optional: Qdrant API key
|
|
QDRANT_TLS=false # Optional: Enable TLS
|
|
OPENAI_API_KEY=sk-... # Required: API key (OpenAI or DeepSeek)
|
|
EMBEDDING_BASE_URL=https://api.openai.com # Optional: base URL (OpenAI by default)
|
|
EMBEDDING_MODEL=text-embedding-3-small # Optional: embedding model
|
|
MCP_TOKEN=my-secret-token # Required: Bearer token for auth
|
|
PORT=8080 # Optional: HTTP port (default: 8080)
|
|
```
|
|
|
|
### Running
|
|
|
|
```bash
|
|
# Using OpenAI embeddings
|
|
export QDRANT_URL=localhost
|
|
export OPENAI_API_KEY=sk-...
|
|
export MCP_TOKEN=my-secret-token
|
|
./st-pierre
|
|
|
|
# Using DeepSeek embeddings
|
|
export OPENAI_API_KEY=sk-...
|
|
export EMBEDDING_BASE_URL=https://api.deepseek.com/v1
|
|
export EMBEDDING_MODEL=deepseek-chat
|
|
export MCP_TOKEN=my-secret-token
|
|
./st-pierre
|
|
```
|
|
|
|
### Nix
|
|
|
|
```bash
|
|
# Build and run directly
|
|
nix run github:didier/st-pierre -- --help
|
|
|
|
# Development shell
|
|
nix develop
|
|
```
|
|
|
|
### NixOS Module
|
|
|
|
```nix
|
|
# flake.nix
|
|
{
|
|
inputs.st-pierre.url = "github:didier/st-pierre";
|
|
...
|
|
}
|
|
|
|
# configuration.nix
|
|
{ inputs, ... }: {
|
|
imports = [ inputs.st-pierre.nixosModules.st-pierre ];
|
|
|
|
services.st-pierre = {
|
|
enable = true;
|
|
port = 8080;
|
|
qdrantUrl = "localhost";
|
|
openaiApiKeyFile = /run/secrets/openai-api-key;
|
|
tokenFile = /run/secrets/mcp-token;
|
|
};
|
|
}
|
|
```
|
|
|
|
The NixOS module creates a dedicated `st-pierre` system user and a systemd
|
|
service. Secrets (API keys, tokens) should be provided as files rather than
|
|
inline strings.
|
|
|
|
## MCP Client Configuration
|
|
|
|
Add to your MCP client config:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"flashcard": {
|
|
"url": "http://your-server:8080/mcp",
|
|
"headers": {
|
|
"Authorization": "Bearer my-secret-token"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|