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.
- factql_mcp-0.1.0/.gitignore +5 -0
- factql_mcp-0.1.0/LICENSE +21 -0
- factql_mcp-0.1.0/PKG-INFO +86 -0
- factql_mcp-0.1.0/README.md +67 -0
- factql_mcp-0.1.0/factql_mcp/__init__.py +1 -0
- factql_mcp-0.1.0/factql_mcp/server.py +136 -0
- factql_mcp-0.1.0/glama.json +4 -0
- factql_mcp-0.1.0/pyproject.toml +31 -0
- factql_mcp-0.1.0/server.json +43 -0
- factql_mcp-0.1.0/test_server.py +29 -0
factql_mcp-0.1.0/LICENSE
ADDED
|
@@ -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,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
|
+
}
|