@gresmcp/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 fairking
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and 
+associated documentation files (the "Software"), to deal in the Software without restriction, including 
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the 
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial 
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT 
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO 
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER 
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE 
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# gresmcp (`@gresmcp/mcp`)
+
+From raw docs to refined answers — Gresy fires your documents into solid Postgres knowledge, entirely local, your MCP.
+
+A Postgres-backed **knowledge source (ks) MCP server** for AI tools, with a management CLI.
+
+Knowledge is stored in PostgreSQL using `pgvector` (semantic similarity) and `tsvector` (full-text search). Queries are answered with **hybrid search** that fuses both signals via Reciprocal Rank Fusion (RRF). Documents are embedded with an [Ollama](https://ollama.com) embedding model; the model is locked per knowledge source so vector dimensions always stay consistent.
+
+- **`gresmcp`** — CLI: create/edit/delete knowledge sources, feed files/folders/url or manual text
+- **`mcp`** — FastMCP server: read-only search/query tools scoped to the knowledge sources you pass on the command line
+
+## Requirements
+
+- Node.js >= 20
+- PostgreSQL with the [`pgvector`](https://github.com/pgvector/pgvector) extension installed (default `gres` database and `gres` user `gres` password used in the examples bellow)
+- An [Ollama](https://ollama.com) server with an embedding model pulled (e.g. `ollama pull nomic-embed-text` or `ollama pull bge-m3`)
+
+Run `gresmcp check` to verify all of these at once (it also creates the `vector` extension for you if it is missing).
+
+## Install
+
+```sh
+npm install -g @gresmcp/mcp
+```
+
+or use it directly with `npx -y @gresmcp/mcp ...` (MCP server) / `npx -y -p @gresmcp/mcp gresmcp ...` (CLI).
+
+## Configuration
+
+Environment variables:
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `GRESMCP_DATABASE_URL` | `postgresql://gres:gres@localhost/gres` | Postgres connection string |
+| `GRESMCP_OLLAMA_URL` | `http://localhost:11434` | Default Ollama base URL |
+| `GRESMCP_KS` | – | Comma-separated ks names for the MCP server (fallback when no arguments are passed) |
+
+## Quickstart
+
+```sh
+# 0. Verify your setup (Node, Postgres, pgvector, schema, Ollama, embedding model)
+gresmcp check --model nomic-embed-text
+
+# 1. Create a knowledge source (probes Ollama to validate the model and detect its dimension)
+gresmcp ks create docs --model nomic-embed-text --description "Project documentation"
+
+# 2. Feed it
+gresmcp feed docs --path ./docs                 # a folder (text, markdown, code, html)
+gresmcp feed docs --path ./README.md            # a single file
+gresmcp feed docs --text "Note: the API key lives in vault" --title "API keys" --tags secrets
+
+# 3. Serve it to your AI tool over MCP
+mcp docs          # stdio transport, scoped to the 'docs' knowledge source
+mcp --all         # every knowledge source in the database
+mcp docs,wiki --transport http --port 8080   # HTTP streaming on http://localhost:8080/mcp
+```
+
+The database schema is created automatically on first run (`CREATE EXTENSION vector`, `ks` table, one entry table per knowledge source).
+
+## CLI reference
+
+### `gresmcp ks create <name> --model <model> [--url <url>] [--description <text>] [--dim <n>]`
+
+Creates a knowledge source. The Ollama server is probed to validate the model and detect the embedding dimension (skip the probe with `--dim`). **The embedding model and dimension are immutable afterwards.**
+
+### `gresmcp ks edit <name> [--url <url>] [--rename <new>] [--description <text>]`
+
+Edits a knowledge source. The Ollama server URL, name and description can change; the model cannot.
+
+### `gresmcp ks list [--json]`
+
+Lists knowledge sources with model, dimension, URL and entry counts.
+
+### `gresmcp ks delete <name> [--yes]`
+
+Deletes a knowledge source and drops its entry table (asks for confirmation unless `--yes`).
+
+### `gresmcp feed <ks> (--path <path> | --text <text> | --stdin) [options]`
+
+Feeds data into a knowledge source. Exactly one input of `--path`, `--text` or `--stdin` must be given.
+
+| Option | Description |
+| --- | --- |
+| `--path <path>` | File or folder. Folders are walked recursively (skips `node_modules`, `.git`, `dist`, ...). Supported: text, markdown, code files, HTML (converted to Markdown via turndown). Binaries and empty files are skipped with a warning. |
+| `--text <text>` / `--stdin` | Manual entry text (chunked the same way as documents) |
+| `--title <title>` | Title for manual entries |
+| `--source-name <name>` | Source name for manual entries (default `manual`) |
+| `--tags a,b` | Tags stored in metadata, filterable by MCP `search` |
+| `--metadata k=v ...` | Repeatable custom metadata entries |
+| `--url <url>` | Ollama URL override for this run (the model stays the ks's) |
+| `--replace` | Replace all chunks of the same source instead of skipping unchanged ones |
+| `--dry-run` | Parse and chunk only; no embeddings, no writes |
+| `--chunk-size <n>` | Max chunk length in characters (default 1200) |
+| `--overlap <n>` | Chunk overlap in characters (default 180) |
+
+Feeding is idempotent: a chunk whose `(source, chunk_index, content hash)` already exists is skipped, so re-running a feed only adds new content. Use `--replace` to force a clean re-ingest of a source.
+
+### `gresmcp init`
+
+Explicitly initializes/repairs the schema (runs automatically for every command anyway).
+
+### `gresmcp check [--model <model>] [--url <url>] [--probe] [--json]`
+
+Verifies that your environment meets all requirements:
+
+| Check | Description |
+| --- | --- |
+| Node | Node.js >= 20 |
+| Postgres | Database reachable at `GRESMCP_DATABASE_URL` |
+| pgvector | Extension installed (created automatically if missing); warns below 0.5.0, which is required for HNSW indexes |
+| schema | `ks` table and every knowledge source's entry table exist (`gresmcp init` repairs them) |
+| Ollama | Server reachable at the configured URL |
+| models | The embedding model of every existing knowledge source (plus `--model`, if given) is pulled at the right URL; `--probe` also embeds a test string to verify the dimension |
+
+```sh
+gresmcp check --model nomic-embed-text
+# ✔ Node v22.14.0 (>= 20 required)
+# ✔ PostgreSQL reachable at postgresql://gres:gres@localhost/gres (PostgreSQL 16.4)
+# ✔ pgvector 0.8.0 installed
+# ✔ schema ready (2 knowledge source(s))
+# ✔ Ollama reachable at http://localhost:11434 (5 model(s))
+# ✔ model 'nomic-embed-text' available at http://localhost:11434 (ks 'docs')
+# all checks passed
+```
+
+The exit code is 1 when any check fails, so it can be used in scripts or CI. `--json` prints the results as machine-readable JSON.
+
+## MCP server reference
+
+```
+mcp <ks1,ks2,...> [--all] [--transport stdio|http] [--port <n>]
+```
+
+The server is **read-only** and hard-scoped to the knowledge sources named at startup; unknown names abort with a helpful message.
+
+| Tool | Description |
+| --- | --- |
+| `search` | Hybrid (default) / vector / keyword search. Returns ranked chunks with `[ks] id, score, source#chunk, title` and a snippet. Supports `ks` (array), `mode`, `limit` (1–50, default 8) and `tags` (any-of metadata filter). |
+| `get_entry` | Full content + metadata of one chunk by id. |
+| `list_entries` | Paginated entry list (id, source, title, chunk index, size), optional `source` filter. |
+| `list_sources` | Ingested documents with chunk counts. |
+| `list_ks` | The configured knowledge sources with entry counts. |
+
+Hybrid mode fuses pgvector cosine ranking and `ts_rank_cd` full-text ranking with Reciprocal Rank Fusion (`score = Σ 1/(60 + rank)`), so results are comparable across knowledge sources even when they use different embedding models.
+
+## Using with AI tools
+
+### opencode
+
+```json
+{
+  "mcp": {
+    "gresmcp": {
+      "type": "local",
+      "command": ["npx", "-y", "@gresmcp/mcp", "ks1,ks2,ks3"],
+      "enabled": true
+    }
+  }
+}
+```
+
+With a global install you can use the binary directly: `["mcp", "ks1,ks2"]`. To scope via environment instead of arguments: `"command": ["npx", "-y", "@gresmcp/mcp", "--all"]` or set `GRESMCP_KS=ks1,ks2`.
+
+### Claude Desktop / generic MCP config
+
+```json
+{
+  "mcpServers": {
+    "gresmcp": {
+      "command": "npx",
+      "args": ["-y", "@gresmcp/mcp", "ks1,ks2"],
+      "env": {
+        "GRESMCP_DATABASE_URL": "postgresql://gres:gres@localhost/gres"
+      }
+    }
+  }
+}
+```
+
+### HTTP transport
+
+```sh
+mcp ks1 --transport http --port 8080
+# MCP endpoint: http://localhost:8080/mcp   (health check: /health)
+```
+
+## Database layout
+
+- `ks` — one row per knowledge source: `id`, `name` (unique), `description`, `embedding_model` (immutable), `embedding_dim`, `ollama_url`, timestamps
+- `entry_<uuid>` — one table per knowledge source (per-ks tables allow different vector dimensions across models): `id`, `source`, `title`, `chunk_index`, `content`, `content_hash`, `metadata jsonb`, generated `tsv tsvector`, `embedding vector(dim)`
+- Indexes: `GIN(tsv)`, `HNSW(embedding vector_cosine_ops)`, `btree(source)`
+
+## Development
+
+```sh
+npm install
+npm run build        # tsup -> dist/cli.js, dist/mcp.js
+npm run typecheck    # tsc --noEmit
+npm test             # vitest (DB integration tests skip gracefully when Postgres/pgvector is unavailable)
+```
+
+Release checklist: `npm version <x.y.z> && npm publish --access public` (the scoped package name `@gresmcp/mcp` must be owned by your npm org).
+
+## Contributors
+
+gresmcp is built on top of these great projects and tools:
+
+| Contributor | Description |
+| --- | --- |
+| [FastMCP](https://gofastmcp.com) | The standard framework for building Model Context Protocol (MCP) servers, clients, and interactive applications (gresmcp uses its TypeScript port) |
+| [Turndown](https://github.com/mixmark-io/turndown) | An HTML to Markdown converter written in JavaScript |
+| [PostgreSQL](https://www.postgresql.org) | The world's most advanced open source database |
+| [Zod](https://zod.dev) | TypeScript-first schema validation library with static type inference |
+| [OpenCode](https://opencode.ai) | The open source AI coding agent |
+| [OpenChamber](https://openchamber.dev) | Agentic development environment for AI coding across desktop, browser, phone, and VS Code |
+| [Ollama](https://ollama.com) | The easiest way to automate your work using open models, while keeping your data safe |
+| [Nano](https://nano.org) | The fast, feeless and eco-friendly digital currency |
+| [NanoGPT](https://nano-gpt.com) | Subscription-free, pay-as-you-go access to AI models |
+| {{ YOU }} | This could be you — issues and PRs welcome at [gitea.com/fairking/gresmcp](https://gitea.com/fairking/gresmcp) |