Skip to content

Commit 4b345bf

Browse files
GioeeGioee
committed
Version 0.1.0: add MCP Rust module; implemented Rust FFI layer exposing functions to C; add SQLite extension interface in to integrate MCP functions with SQLite; add test suite to validate the extension functionality; add markdown Docs to show APIs and explain usage; add Makefile to allow users to local build the extension; add Swift Package Manager support; implemented workflow to build, test and release the extension; release Android package on Maven Central; add Android JitPack package support
1 parent 44a453b commit 4b345bf

38 files changed

+281509
-0
lines changed

‎.github/workflows/main.yml‎

Lines changed: 456 additions & 0 deletions
Large diffs are not rendered by default.

‎.gitignore‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# Build artifacts
2+
build/
3+
dist/
4+
.build
5+
*.a
6+
*.sqlite
7+
target/
8+
9+
# Rust
10+
Cargo.lock
11+
**/*.rs.bk
12+
*.pdb
13+
14+
# iOS/macOS
15+
*.xcworkspacedata
16+
*.xcuserstate
17+
*.xcbkptlist
18+
*.plist
19+
*.xcframework
20+
*.dylib
21+
22+
# Android
23+
.gradle/
24+
*.aar
25+
local.properties
26+
jniLibs/
27+
*.apk
28+
*.ap_
29+
*.dex
30+
31+
# Node.js
32+
node_modules/
33+
package-lock.json
34+
*.tsbuildinfo
35+
coverage/
36+
*.log
37+
npm-debug.log*
38+
yarn-debug.log*
39+
yarn-error.log*
40+
packages/node/platform-packages/
41+
packages/node/test-artifacts/
42+
packages/node/test-output/
43+
packages/node/test-platform-packages/
44+
45+
# IDE
46+
.vscode
47+
.idea/
48+
*.iml
49+
*.swp
50+
*.swo
51+
52+
# System
53+
.DS_Store
54+
Thumbs.db
55+
*.db

‎.gitmodules‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "modules/mcp"]
2+
path = modules/mcp
3+
url = https://github.com/modelcontextprotocol/rust-sdk

‎API.md‎

Lines changed: 214 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,214 @@
1+
# SQLite MCP Extension API Reference
2+
3+
## Overview
4+
5+
The SQLite MCP extension provides full integration with the Model Context Protocol (MCP), enabling SQLite databases to connect to MCP servers and call tools.
6+
7+
---
8+
9+
## SQL Functions
10+
11+
### `mcp_version()`
12+
13+
Returns the version of the MCP extension.
14+
15+
**Syntax:**
16+
```sql
17+
SELECT mcp_version();
18+
```
19+
20+
**Returns:** `TEXT` - The version string (e.g., "0.1.0")
21+
22+
**Example:**
23+
```sql
24+
sqlite> SELECT mcp_version();
25+
0.1.0
26+
```
27+
28+
---
29+
30+
### `mcp_connect(server_url, [legacy_sse], [headers_json])`
31+
32+
Connects to an MCP server using either Streamable HTTP (default) or SSE transport, with optional custom HTTP headers.
33+
34+
**Syntax:**
35+
```sql
36+
SELECT mcp_connect(server_url);
37+
SELECT mcp_connect(server_url, legacy_sse);
38+
SELECT mcp_connect(server_url, legacy_sse, headers_json);
39+
```
40+
41+
**Parameters:**
42+
- `server_url` (TEXT) - URL of the MCP server (e.g., "http://localhost:8000/mcp")
43+
- `legacy_sse` (INTEGER, optional) - 1 to use SSE transport (legacy), 0 for Streamable HTTP (default)
44+
- `headers_json` (TEXT, optional) - JSON string with custom HTTP headers (e.g., `{"Authorization": "Bearer token"}`)
45+
46+
**Returns:** `TEXT` - JSON object with connection status
47+
48+
**Examples:**
49+
```sql
50+
-- Connect using Streamable HTTP (default)
51+
SELECT mcp_connect('http://localhost:8000/mcp');
52+
53+
-- Connect using legacy SSE transport
54+
SELECT mcp_connect('http://localhost:8931/sse', 1);
55+
56+
-- Connect with authorization header (GitHub Copilot)
57+
SELECT mcp_connect(
58+
'https://api.githubcopilot.com/mcp/',
59+
0,
60+
'{"Authorization": "Bearer ghp_your_token", "X-MCP-Readonly": "true"}'
61+
);
62+
```
63+
64+
**Response:**
65+
```json
66+
{"status": "connected", "transport": "streamable_http"}
67+
```
68+
69+
See [USAGE.md](USAGE.md) for more examples of using custom headers.
70+
71+
---
72+
73+
### `mcp_list_tools()`
74+
75+
Lists all tools available on the connected MCP server with their complete signatures.
76+
77+
**Syntax:**
78+
```sql
79+
SELECT mcp_list_tools();
80+
```
81+
82+
**Returns:** `TEXT` - JSON array of tool definitions including:
83+
- Tool name
84+
- Description
85+
- Complete input schema with all parameters
86+
- Required vs optional parameters
87+
88+
**Example:**
89+
```sql
90+
sqlite> SELECT mcp_connect('http://localhost:8000/mcp');
91+
sqlite> SELECT mcp_list_tools();
92+
```
93+
94+
**Response:**
95+
```json
96+
{
97+
"tools": [
98+
{
99+
"name": "airbnb_search",
100+
"description": "Search for Airbnb listings with various filters",
101+
"inputSchema": {
102+
"type": "object",
103+
"properties": {
104+
"location": {
105+
"type": "string",
106+
"description": "Location to search for"
107+
},
108+
"maxPrice": {
109+
"type": "number",
110+
"description": "Maximum price per night"
111+
},
112+
"adults": {
113+
"type": "number",
114+
"description": "Number of adults"
115+
}
116+
},
117+
"required": ["location"]
118+
}
119+
}
120+
]
121+
}
122+
```
123+
124+
---
125+
126+
### `mcp_call_tool(tool_name, arguments_json)`
127+
128+
Calls a tool on the connected MCP server.
129+
130+
**Syntax:**
131+
```sql
132+
SELECT mcp_call_tool(tool_name, arguments_json);
133+
```
134+
135+
**Parameters:**
136+
- `tool_name` (TEXT) - Name of the tool to call
137+
- `arguments_json` (TEXT) - JSON object containing tool arguments
138+
139+
**Returns:** `TEXT` - JSON response from the tool
140+
141+
**Example:**
142+
```sql
143+
SELECT mcp_call_tool(
144+
'airbnb_search',
145+
'{"location": "Rome", "maxPrice": 100, "adults": 2}'
146+
);
147+
```
148+
149+
**Response:**
150+
```json
151+
{
152+
"result": {
153+
"content": [
154+
{
155+
"type": "text",
156+
"text": "{\"listings\": [{\"title\": \"Cozy Apartment\", \"price\": 85}]}"
157+
}
158+
]
159+
}
160+
}
161+
```
162+
163+
**Error Handling:**
164+
```sql
165+
-- Returns error if not connected
166+
SELECT mcp_call_tool('test', '{}');
167+
-- {"error": "Not connected. Call mcp_connect() first"}
168+
```
169+
170+
---
171+
172+
## Transport Protocols
173+
174+
The extension supports two MCP transport protocols:
175+
176+
### Streamable HTTP (Default)
177+
Modern streaming HTTP transport for MCP servers.
178+
179+
```sql
180+
SELECT mcp_connect('http://localhost:8000/mcp');
181+
SELECT mcp_connect('http://localhost:8000/mcp', 0); -- Explicit
182+
```
183+
184+
### SSE (Legacy)
185+
Server-Sent Events transport for compatibility with older MCP servers.
186+
187+
```sql
188+
SELECT mcp_connect('http://localhost:8931/sse', 1);
189+
```
190+
191+
---
192+
193+
## Error Handling
194+
195+
All functions return JSON with error information on failure:
196+
197+
```json
198+
{"error": "Connection failed: timeout"}
199+
{"error": "Not connected. Call mcp_connect() first"}
200+
{"error": "Tool not found: invalid_tool"}
201+
{"error": "Invalid JSON arguments"}
202+
```
203+
204+
Use SQLite's `json_extract()` to handle errors:
205+
206+
```sql
207+
SELECT
208+
CASE
209+
WHEN json_extract(result, '$.error') IS NOT NULL
210+
THEN 'Error: ' || json_extract(result, '$.error')
211+
ELSE 'Success'
212+
END
213+
FROM (SELECT mcp_call_tool('test', '{}') as result);
214+
```

‎Cargo.toml‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
[package]
2+
name = "mcp-ffi"
3+
version = "0.1.0"
4+
edition = "2021"
5+
6+
[dependencies]
7+
rmcp = { path = "modules/mcp/crates/rmcp", features = ["server", "client", "transport-sse-client-reqwest", "transport-streamable-http-client-reqwest", "reqwest"] }
8+
tokio = { version = "1", features = ["full"] }
9+
serde_json = "1.0"
10+
reqwest = { version = "0.12", features = ["json"] }
11+
lazy_static = "1.4"
12+
13+
[lib]
14+
name = "mcp_ffi"
15+
crate-type = ["staticlib"]
16+
17+
[profile.release]
18+
opt-level = 3
19+
lto = true

0 commit comments

Comments
 (0)