factql-mcp 0.1.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.
@@ -0,0 +1,5 @@
1
+ __pycache__/
2
+ *.pyc
3
+ .venv/
4
+ dist/
5
+ uv.lock
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 FactQL
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,86 @@
1
+ Metadata-Version: 2.5
2
+ Name: factql-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for FactQL: ask plain-English questions of your database from Claude, Cursor or any MCP client.
5
+ Project-URL: Homepage, https://factql.ai
6
+ Project-URL: Documentation, https://docs.factql.ai
7
+ Project-URL: Repository, https://github.com/factql/factql-mcp
8
+ Author: FactQL
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: analytics,claude,mcp,model-context-protocol,nl2sql,text-to-sql
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Topic :: Database
14
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
15
+ Requires-Python: >=3.10
16
+ Requires-Dist: httpx>=0.27
17
+ Requires-Dist: mcp<3,>=2
18
+ Description-Content-Type: text/markdown
19
+
20
+ # factql-mcp
21
+
22
+ Ask plain-English questions of your business data from Claude Desktop, Claude Code, Cursor, or any MCP client. [FactQL](https://factql.ai) turns the question into SQL, runs it read-only against your connected database, and returns the answer, the SQL it ran, and the rows.
23
+
24
+ <!-- mcp-name: io.github.factql/factql-mcp -->
25
+
26
+ ## Get a key
27
+
28
+ Sign up free at [factql.ai/signup](https://factql.ai/signup), connect your database, and create an API key. An ask-only key is enough for this server.
29
+
30
+ ## Install
31
+
32
+ ```bash
33
+ uvx factql-mcp
34
+ ```
35
+
36
+ or `pip install factql-mcp`.
37
+
38
+ ## Configure
39
+
40
+ | Variable | Required | Default |
41
+ |---|---|---|
42
+ | `FACTQL_API_KEY` | yes | — your FactQL API key (an ask-only key is enough) |
43
+ | `FACTQL_BASE_URL` | no | `https://api.factql.ai` |
44
+ | `FACTQL_WORKSPACE_ID` | no | default workspace, for tenants that use workspaces |
45
+ | `FACTQL_END_USER_ID` | no | `mcp:<os user>` |
46
+
47
+ ### Claude Desktop / Cursor (`mcpServers`)
48
+
49
+ ```json
50
+ {
51
+ "mcpServers": {
52
+ "factql": {
53
+ "command": "uvx",
54
+ "args": ["factql-mcp"],
55
+ "env": { "FACTQL_API_KEY": "fl_live_..." }
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ ### Claude Code
62
+
63
+ ```bash
64
+ claude mcp add factql -e FACTQL_API_KEY=fl_live_... -- uvx factql-mcp
65
+ ```
66
+
67
+ ## Tools
68
+
69
+ - `whoami()` — the tenant, plan, and workspaces this key can query.
70
+ - `ask(question, workspace_id?, locale?)` — the answer, the SQL that ran, and up to 50 rows. A `needs_clarification` result means the question was too vague; ask the user and call again with the detail. `locale` is `en-GB` or `en-US`.
71
+
72
+ Each `ask` is stateless: the MCP client carries the conversation, so a follow-up should restate what it refers to.
73
+
74
+ ## Safety
75
+
76
+ FactQL only runs `SELECT` queries, under a statement timeout, and only against the tables your admin has enabled. The key's permissions decide what it can see; this server adds nothing on top.
77
+
78
+ ## Development
79
+
80
+ ```bash
81
+ uv run --with pytest pytest -q
82
+ ```
83
+
84
+ ## License
85
+
86
+ MIT
@@ -0,0 +1,67 @@
1
+ # factql-mcp
2
+
3
+ Ask plain-English questions of your business data from Claude Desktop, Claude Code, Cursor, or any MCP client. [FactQL](https://factql.ai) turns the question into SQL, runs it read-only against your connected database, and returns the answer, the SQL it ran, and the rows.
4
+
5
+ <!-- mcp-name: io.github.factql/factql-mcp -->
6
+
7
+ ## Get a key
8
+
9
+ Sign up free at [factql.ai/signup](https://factql.ai/signup), connect your database, and create an API key. An ask-only key is enough for this server.
10
+
11
+ ## Install
12
+
13
+ ```bash
14
+ uvx factql-mcp
15
+ ```
16
+
17
+ or `pip install factql-mcp`.
18
+
19
+ ## Configure
20
+
21
+ | Variable | Required | Default |
22
+ |---|---|---|
23
+ | `FACTQL_API_KEY` | yes | — your FactQL API key (an ask-only key is enough) |
24
+ | `FACTQL_BASE_URL` | no | `https://api.factql.ai` |
25
+ | `FACTQL_WORKSPACE_ID` | no | default workspace, for tenants that use workspaces |
26
+ | `FACTQL_END_USER_ID` | no | `mcp:<os user>` |
27
+
28
+ ### Claude Desktop / Cursor (`mcpServers`)
29
+
30
+ ```json
31
+ {
32
+ "mcpServers": {
33
+ "factql": {
34
+ "command": "uvx",
35
+ "args": ["factql-mcp"],
36
+ "env": { "FACTQL_API_KEY": "fl_live_..." }
37
+ }
38
+ }
39
+ }
40
+ ```
41
+
42
+ ### Claude Code
43
+
44
+ ```bash
45
+ claude mcp add factql -e FACTQL_API_KEY=fl_live_... -- uvx factql-mcp
46
+ ```
47
+
48
+ ## Tools
49
+
50
+ - `whoami()` — the tenant, plan, and workspaces this key can query.
51
+ - `ask(question, workspace_id?, locale?)` — the answer, the SQL that ran, and up to 50 rows. A `needs_clarification` result means the question was too vague; ask the user and call again with the detail. `locale` is `en-GB` or `en-US`.
52
+
53
+ Each `ask` is stateless: the MCP client carries the conversation, so a follow-up should restate what it refers to.
54
+
55
+ ## Safety
56
+
57
+ FactQL only runs `SELECT` queries, under a statement timeout, and only against the tables your admin has enabled. The key's permissions decide what it can see; this server adds nothing on top.
58
+
59
+ ## Development
60
+
61
+ ```bash
62
+ uv run --with pytest pytest -q
63
+ ```
64
+
65
+ ## License
66
+
67
+ MIT
@@ -0,0 +1 @@
1
+ __version__ = "0.1.0"
@@ -0,0 +1,136 @@
1
+ """FactQL MCP server — a thin wrapper over ``POST /query``.
2
+
3
+ Configure with environment variables:
4
+
5
+ FACTQL_API_KEY required. A FactQL API key (a query-only key is enough).
6
+ FACTQL_BASE_URL default https://api.factql.ai
7
+ FACTQL_WORKSPACE_ID default workspace when the tenant uses workspaces.
8
+ FACTQL_END_USER_ID who is asking; default "mcp:<os user>". Query-only keys
9
+ require it on tenant routes.
10
+
11
+ Every question is a fresh, stateless ``/query`` call: the MCP client carries the
12
+ conversation, so a follow-up must restate what it refers to.
13
+ """
14
+
15
+ from __future__ import annotations
16
+
17
+ import getpass
18
+ import os
19
+ from typing import Any, Optional
20
+
21
+ import httpx
22
+ from mcp.server import MCPServer
23
+
24
+ BASE_URL = os.environ.get("FACTQL_BASE_URL", "https://api.factql.ai").rstrip("/")
25
+ ROW_CAP = 50
26
+ _PASS_THROUGH = (
27
+ "type",
28
+ "result",
29
+ "explanation",
30
+ "answer",
31
+ "sql",
32
+ "total_rows",
33
+ "clarification_request",
34
+ "suggestions",
35
+ "sources",
36
+ "chart",
37
+ "chart_spec",
38
+ "locale",
39
+ "budget_alerts",
40
+ "error",
41
+ "detail",
42
+ )
43
+
44
+ server = MCPServer(
45
+ "factql",
46
+ instructions=(
47
+ "Ask plain-English questions about the connected business data. Call "
48
+ "`whoami` first when the tenant may use workspaces, then pass the "
49
+ "workspace_id to `ask`. Each `ask` is stateless: restate the subject in "
50
+ "follow-up questions."
51
+ ),
52
+ )
53
+
54
+
55
+ def _headers() -> dict[str, str]:
56
+ key = os.environ.get("FACTQL_API_KEY")
57
+ if not key:
58
+ raise RuntimeError("FACTQL_API_KEY is not set")
59
+ return {
60
+ "X-API-Key": key,
61
+ "X-End-User-Id": os.environ.get("FACTQL_END_USER_ID")
62
+ or f"mcp:{getpass.getuser()}",
63
+ }
64
+
65
+
66
+ def _client() -> httpx.Client:
67
+ return httpx.Client(base_url=BASE_URL, headers=_headers(), timeout=120.0)
68
+
69
+
70
+ def _error(res: httpx.Response) -> dict[str, Any]:
71
+ try:
72
+ detail = res.json()
73
+ except ValueError:
74
+ detail = res.text
75
+ return {"error": f"HTTP {res.status_code}", "detail": detail}
76
+
77
+
78
+ def shape_answer(payload: dict[str, Any]) -> dict[str, Any]:
79
+ """Keep what a model needs from an /ask-shaped payload; cap the rows."""
80
+ out = {k: payload[k] for k in _PASS_THROUGH if payload.get(k) is not None}
81
+ data = payload.get("data") or {}
82
+ rows = data.get("rows") or []
83
+ if rows or data.get("columns"):
84
+ out["columns"] = data.get("columns") or []
85
+ out["rows"] = rows[:ROW_CAP]
86
+ out["row_count"] = payload.get("total_rows") or len(rows)
87
+ if len(rows) > ROW_CAP:
88
+ out["note"] = f"Showing the first {ROW_CAP} of {len(rows)} returned rows."
89
+ return out
90
+
91
+
92
+ @server.tool()
93
+ def whoami() -> dict[str, Any]:
94
+ """What this API key can see: tenant, plan, and the workspaces it may query.
95
+
96
+ Use it to find a `workspace_id` before calling `ask` on a tenant that
97
+ uses workspaces."""
98
+ with _client() as c:
99
+ res = c.get("/whoami")
100
+ return res.json() if res.is_success else _error(res)
101
+
102
+
103
+ @server.tool()
104
+ def ask(
105
+ question: str,
106
+ workspace_id: Optional[str] = None,
107
+ locale: Optional[str] = None,
108
+ ) -> dict[str, Any]:
109
+ """Ask a plain-English question about the connected data.
110
+
111
+ Returns the answer, the SQL that was run (when any), and up to 50 rows.
112
+ `workspace_id` scopes the question when the tenant uses workspaces
113
+ (see `whoami`); `locale` is "en-GB" or "en-US" for the answer's wording.
114
+ A `needs_clarification` result means the question was too vague: ask the
115
+ user, then call again with the detail."""
116
+ body: dict[str, Any] = {"q": question}
117
+ ws = workspace_id or os.environ.get("FACTQL_WORKSPACE_ID")
118
+ if ws:
119
+ body["workspace_id"] = ws
120
+ if locale:
121
+ body["locale"] = locale
122
+ with _client() as c:
123
+ res = c.post("/query", json=body)
124
+ if not res.is_success:
125
+ return _error(res)
126
+ payload = res.json()
127
+ return shape_answer(payload) if isinstance(payload, dict) else {"answer": payload}
128
+
129
+
130
+ def main() -> None:
131
+ _headers() # fail at startup, not on the first question
132
+ server.run("stdio")
133
+
134
+
135
+ if __name__ == "__main__":
136
+ main()
@@ -0,0 +1,4 @@
1
+ {
2
+ "$schema": "https://glama.ai/mcp/schemas/server.json",
3
+ "maintainers": ["factql-team"]
4
+ }
@@ -0,0 +1,31 @@
1
+ [project]
2
+ name = "factql-mcp"
3
+ version = "0.1.0"
4
+ description = "MCP server for FactQL: ask plain-English questions of your database from Claude, Cursor or any MCP client."
5
+ readme = "README.md"
6
+ requires-python = ">=3.10"
7
+ license = "MIT"
8
+ license-files = ["LICENSE"]
9
+ authors = [{ name = "FactQL" }]
10
+ keywords = ["mcp", "model-context-protocol", "text-to-sql", "nl2sql", "analytics", "claude"]
11
+ classifiers = [
12
+ "Programming Language :: Python :: 3",
13
+ "Topic :: Database",
14
+ "Topic :: Scientific/Engineering :: Artificial Intelligence",
15
+ ]
16
+ dependencies = ["mcp>=2,<3", "httpx>=0.27"]
17
+
18
+ [project.urls]
19
+ Homepage = "https://factql.ai"
20
+ Documentation = "https://docs.factql.ai"
21
+ Repository = "https://github.com/factql/factql-mcp"
22
+
23
+ [project.scripts]
24
+ factql-mcp = "factql_mcp.server:main"
25
+
26
+ [build-system]
27
+ requires = ["hatchling"]
28
+ build-backend = "hatchling.build"
29
+
30
+ [tool.hatch.build.targets.wheel]
31
+ packages = ["factql_mcp"]
@@ -0,0 +1,43 @@
1
+ {
2
+ "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
3
+ "name": "io.github.factql/factql-mcp",
4
+ "title": "FactQL",
5
+ "description": "Ask plain-English questions of your database: answers, the SQL that ran, and the rows.",
6
+ "websiteUrl": "https://factql.ai",
7
+ "repository": {
8
+ "url": "https://github.com/factql/factql-mcp",
9
+ "source": "github"
10
+ },
11
+ "version": "0.1.0",
12
+ "packages": [
13
+ {
14
+ "registryType": "pypi",
15
+ "registryBaseUrl": "https://pypi.org",
16
+ "identifier": "factql-mcp",
17
+ "version": "0.1.0",
18
+ "runtimeHint": "uvx",
19
+ "transport": { "type": "stdio" },
20
+ "environmentVariables": [
21
+ {
22
+ "name": "FACTQL_API_KEY",
23
+ "description": "FactQL API key (an ask-only key is enough)",
24
+ "isRequired": true,
25
+ "isSecret": true
26
+ },
27
+ {
28
+ "name": "FACTQL_BASE_URL",
29
+ "description": "FactQL API base URL",
30
+ "default": "https://api.factql.ai"
31
+ },
32
+ {
33
+ "name": "FACTQL_WORKSPACE_ID",
34
+ "description": "Default workspace, for tenants that use workspaces"
35
+ },
36
+ {
37
+ "name": "FACTQL_END_USER_ID",
38
+ "description": "Who is asking; defaults to mcp:<os user>"
39
+ }
40
+ ]
41
+ }
42
+ ]
43
+ }
@@ -0,0 +1,29 @@
1
+ """One check: the shape a model sees. Run: uv run --with pytest pytest -q"""
2
+
3
+ from factql_mcp.server import ROW_CAP, shape_answer
4
+
5
+
6
+ def test_shape_answer_caps_rows_and_keeps_the_answer():
7
+ payload = {
8
+ "type": "text2sql",
9
+ "result": "success",
10
+ "sql": "SELECT 1",
11
+ "explanation": "Found 60 records.",
12
+ "thinking": "internal", # dropped
13
+ "data": {"columns": ["n"], "rows": [[i] for i in range(60)]},
14
+ }
15
+ out = shape_answer(payload)
16
+ assert out["sql"] == "SELECT 1" and out["explanation"] == "Found 60 records."
17
+ assert "thinking" not in out
18
+ assert len(out["rows"]) == ROW_CAP and out["row_count"] == 60
19
+ assert out["note"].startswith("Showing the first 50")
20
+
21
+
22
+ def test_shape_answer_passes_clarification_through():
23
+ out = shape_answer(
24
+ {"result": "needs_clarification", "clarification_request": "Which year?"}
25
+ )
26
+ assert out == {
27
+ "result": "needs_clarification",
28
+ "clarification_request": "Which year?",
29
+ }