0 Fork 0

Files

T

didier e700a81c25 Add versioning, update tool, and soft-delete

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).

2026-06-03 20:15:18 -04:00

2.7 KiB

Raw Blame History

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

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

# 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

# Build and run directly
nix run github:didier/st-pierre -- --help

# Development shell
nix develop

NixOS Module

# 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:

{
  "mcpServers": {
    "flashcard": {
      "url": "http://your-server:8080/mcp",
      "headers": {
        "Authorization": "Bearer my-secret-token"
      }
    }
  }
}

2.7 KiB Raw Blame History