Skip to content

Commit a94702c

Browse files
galshubeliduwenxin99
galshubeli
and
duwenxin99
authored
feat(falkordb): add FalkorDB source and tools (#3692)
## Description Adds [FalkorDB](https://docs.falkordb.com/) — an open-source, low-latency graph database that speaks openCypher over the Redis protocol — as a supported source, modeled on the existing Neo4j integration. **What's included:** - **Source `falkordb`** (`internal/sources/falkordb/`) — connects via the official [`falkordb-go/v2`](https://github.com/FalkorDB/falkordb-go) client, which is built on `go-redis/v9` (already a toolbox dependency). Config: `host`, `port`, optional `username`/`password`/`tls`, a default `graph`, and `queryTimeoutMs`. - **Tool `falkordb-cypher`** — developer-authored parameterized Cypher statements (injection-safe via the client's parameter serialization). - **Tool `falkordb-execute-cypher`** — agent-authored queries. With `readOnly: true` queries are dispatched as `GRAPH.RO_QUERY`, so **the server itself rejects writes** (no client-side query classifier needed). A `dry_run` parameter returns the `GRAPH.EXPLAIN` execution plan without executing, and an opt-in `allowGraphOverride` flag exposes a `graph` parameter for multi-graph instances. Write queries return mutation counters (`nodesCreated`, `propertiesSet`, …). - **Tool `falkordb-schema`** — concurrent extraction of node labels, relationship types, sampled property shapes, connectivity patterns, indexes (including vector/full-text), constraints, and statistics, with a configurable TTL cache. Graphs that don't exist yet (FalkorDB creates graph keys lazily) return a valid empty schema. - **Tool `falkordb-list-graphs`** — lists the graphs on the instance via `GRAPH.LIST`. - **`--prebuilt falkordb`** config driven by `FALKORDB_HOST`/`FALKORDB_PORT`/`FALKORDB_GRAPH`/`FALKORDB_USERNAME`/`FALKORDB_PASSWORD`. - **Docs** under `docs/en/integrations/falkordb/` (source page, four tool pages, prebuilt-config page, MCP quickstart) — passing `.ci/lint-docs-source-page.sh`, `.ci/lint-docs-tool-page.sh`, and `.ci/lint-docs-sample-filters.sh`. - **Tests**: unit tests for every package, and an integration suite (`tests/falkordb/`, 14 subtests) covering manifests and all four tools over the HTTP API — including read-only rejection, dry-run plans, graph override + isolation, mutation stats, empty-graph schema, and populated schema extraction. - **CI**: a `falkordb` shard in `.ci/integration.cloudbuild.yaml` mirroring the Neo4j one. **Testing done:** `go test -race` green on all new packages; the integration suite passes against a live `falkordb/falkordb` container; `golangci-lint run` reports 0 issues; `go mod tidy` is clean; manually smoke-tested `--prebuilt falkordb` over both the `/api` and `/mcp` endpoints (MCP Inspector flow). **Note for maintainers:** the CI shard needs a FalkorDB instance reachable from the integration test project (a `falkordb/falkordb` container) and `falkordb_username`/`falkordb_password` secrets. Happy to coordinate on provisioning — see the issue below. FalkorDB (the company) will maintain this integration going forward. ## PR Checklist - [x] Make sure to open an issue as a bug/issue before writing your code! - [x] Ensure the tests and linter pass - [x] Code coverage does not decrease (if any source code was changed) - [x] Appropriate docs were updated (if necessary) - [ ] Make sure to add `!` if this involves a breaking change (not a breaking change) Fixes #3691 🦕 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Wenxin Du <117315983+duwenxin99@users.noreply.github.com> Co-authored-by: duwenxin99 
1 parent a8d54a1 commit a94702c

32 files changed

Lines changed: 3256 additions & 0 deletions

‎.ci/integration.cloudbuild.yaml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -628,6 +628,32 @@ steps:
628628
exit 0
629629
fi
630630
631+
- id: "falkordb"
632+
name: golang:1
633+
waitFor: ["compile-test-binary", "detect-changes"]
634+
entrypoint: /bin/bash
635+
env:
636+
- "GOPATH=/gopath"
637+
secretEnv: ["API_KEY"]
638+
volumes:
639+
- name: "go"
640+
path: "/gopath"
641+
args:
642+
- -c
643+
- |
644+
PATTERN="(^|/)falkordb/|$$(cat .ci/core_pattern.txt)"
645+
646+
if grep -qE "$$PATTERN" /workspace/changed_files.txt; then
647+
echo "Changes detected. Running FalkorDB tests..."
648+
.ci/test_with_coverage.sh \
649+
"FalkorDB" \
650+
falkordb \
651+
falkordb
652+
else
653+
echo "No relevant changes for FalkorDB. Skipping shard."
654+
exit 0
655+
fi
656+
631657
- id: "cloud-sql-mssql"
632658
name: golang:1
633659
waitFor: ["compile-test-binary", "detect-changes"]

‎.hugo/data/filters.yaml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@
1515
data_sources:
1616
- AlloyDB
1717
- BigQuery
18+
- FalkorDB
1819
- Looker
1920
- Neo4j
2021
- Snowflake

‎cmd/internal/imports.go‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ import (
4242
_ "github.com/googleapis/mcp-toolbox/internal/sources/dataproc"
4343
_ "github.com/googleapis/mcp-toolbox/internal/sources/dgraph"
4444
_ "github.com/googleapis/mcp-toolbox/internal/sources/elasticsearch"
45+
_ "github.com/googleapis/mcp-toolbox/internal/sources/falkordb"
4546
_ "github.com/googleapis/mcp-toolbox/internal/sources/firebird"
4647
_ "github.com/googleapis/mcp-toolbox/internal/sources/firestore"
4748
_ "github.com/googleapis/mcp-toolbox/internal/sources/http"
@@ -226,6 +227,10 @@ import (
226227
_ "github.com/googleapis/mcp-toolbox/internal/tools/dgraph"
227228
_ "github.com/googleapis/mcp-toolbox/internal/tools/elasticsearch/elasticsearchesql"
228229
_ "github.com/googleapis/mcp-toolbox/internal/tools/elasticsearch/elasticsearchexecuteesql"
230+
_ "github.com/googleapis/mcp-toolbox/internal/tools/falkordb/falkordbcypher"
231+
_ "github.com/googleapis/mcp-toolbox/internal/tools/falkordb/falkordbexecutecypher"
232+
_ "github.com/googleapis/mcp-toolbox/internal/tools/falkordb/falkordblistgraphs"
233+
_ "github.com/googleapis/mcp-toolbox/internal/tools/falkordb/falkordbschema"
229234
_ "github.com/googleapis/mcp-toolbox/internal/tools/firebird/firebirdexecutesql"
230235
_ "github.com/googleapis/mcp-toolbox/internal/tools/firebird/firebirdsql"
231236
_ "github.com/googleapis/mcp-toolbox/internal/tools/firestore/firestoreadddocuments"

‎docs/en/integrations/falkordb/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "FalkorDB"
3+
weight: 1
4+
---

‎docs/en/integrations/falkordb/prebuilt-configs/_index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
title: "Prebuilt Configs"
3+
type: docs
4+
description: "Prebuilt configurations for FalkorDB."
5+
---

‎docs/en/integrations/falkordb/prebuilt-configs/falkordb.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
---
2+
title: "FalkorDB"
3+
type: docs
4+
description: "Details of the FalkorDB prebuilt configuration."
5+
---
6+
7+
## FalkorDB
8+
9+
* `--prebuilt` value: `falkordb`
10+
* **Environment Variables:**
11+
* `FALKORDB_HOST`: The host of the FalkorDB instance (e.g.,
12+
`127.0.0.1`).
13+
* `FALKORDB_PORT`: The port of the FalkorDB instance (defaults to
14+
`6379`).
15+
* `FALKORDB_GRAPH`: The name of the graph to operate on.
16+
* `FALKORDB_USERNAME`: The username for the FalkorDB instance
17+
(optional).
18+
* `FALKORDB_PASSWORD`: The password for the FalkorDB instance
19+
(optional).
20+
* **Permissions:**
21+
* **Database-level permissions** are required to execute Cypher
22+
queries.
23+
* **Tools:**
24+
* `execute_cypher`: Executes a Cypher query against the graph.
25+
* `get_schema`: Retrieves the schema of the graph.
26+
* `list_graphs`: Lists the graphs stored on the instance.

‎docs/en/integrations/falkordb/samples/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Samples"
3+
weight: 3
4+
---

‎docs/en/integrations/falkordb/samples/mcp_quickstart.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
title: "Quickstart (MCP with FalkorDB)"
3+
type: docs
4+
weight: 1
5+
description: >
6+
How to get started running Toolbox with MCP Inspector and FalkorDB as the source.
7+
sample_filters: ["FalkorDB", "MCP Inspector"]
8+
is_sample: true
9+
---
10+
11+
## Overview
12+
13+
[Model Context Protocol](https://modelcontextprotocol.io) is an open protocol
14+
that standardizes how applications provide context to LLMs. Check out this page
15+
on how to [connect to Toolbox via
16+
MCP](../../../documentation/connect-to/mcp-client/_index.md).
17+
18+
## Step 1: Set up your FalkorDB graph and data
19+
20+
In this section, you'll start a FalkorDB instance and populate it with sample
21+
data for a movies-related agent.
22+
23+
1. **Start FalkorDB.** The quickest way is Docker:
24+
25+
```bash
26+
docker run -d --name falkordb -p 6379:6379 falkordb/falkordb
27+
```
28+
29+
1. **Populate the graph with data.** Using `redis-cli` (or the FalkorDB
30+
browser at `http://localhost:3000` if you expose it), create a small movie
31+
graph:
32+
33+
```bash
34+
docker exec falkordb redis-cli GRAPH.QUERY movies "CREATE
35+
(hanks:Person {name: 'Tom Hanks'}),
36+
(ryan:Person {name: 'Meg Ryan'}),
37+
(sleepless:Movie {title: 'Sleepless in Seattle', year: 1993}),
38+
(gump:Movie {title: 'Forrest Gump', year: 1994}),
39+
(hanks)-[:ACTED_IN]->(sleepless),
40+
(hanks)-[:ACTED_IN]->(gump),
41+
(ryan)-[:ACTED_IN]->(sleepless)"
42+
```
43+
44+
## Step 2: Install and configure Toolbox
45+
46+
In this section, we will download Toolbox and run the Toolbox server with a
47+
FalkorDB configuration.
48+
49+
1. Download the latest version of Toolbox as a binary. Select the [correct
50+
binary](https://github.com/googleapis/mcp-toolbox/releases) corresponding
51+
to your OS and CPU architecture.
52+
53+
1. Make the binary executable:
54+
55+
```bash
56+
chmod +x toolbox
57+
```
58+
59+
1. Write the following into a `tools.yaml` file:
60+
61+
```yaml
62+
kind: source
63+
name: falkordb-movies
64+
type: falkordb
65+
host: 127.0.0.1
66+
port: "6379"
67+
graph: movies
68+
---
69+
kind: tool
70+
name: search_movies_by_actor
71+
type: falkordb-cypher
72+
source: falkordb-movies
73+
statement: |
74+
MATCH (m:Movie)<-[:ACTED_IN]-(p:Person)
75+
WHERE p.name = $name
76+
RETURN m.title, m.year
77+
LIMIT 10
78+
description: Use this tool to list the movies a given actor acted in.
79+
parameters:
80+
- name: name
81+
type: string
82+
description: Full name of the actor.
83+
---
84+
kind: tool
85+
name: execute_cypher
86+
type: falkordb-execute-cypher
87+
source: falkordb-movies
88+
description: Use this tool to execute a Cypher query against the movie graph.
89+
---
90+
kind: tool
91+
name: get_schema
92+
type: falkordb-schema
93+
source: falkordb-movies
94+
description: Use this tool to get the schema of the movie graph.
95+
```
96+
97+
1. Start the Toolbox server:
98+
99+
```bash
100+
./toolbox --tools-file "tools.yaml"
101+
```
102+
103+
## Step 3: Connect to MCP Inspector
104+
105+
1. Run the MCP Inspector:
106+
107+
```bash
108+
npx @modelcontextprotocol/inspector
109+
```
110+
111+
1. Type `y` when it asks to install the inspector package.
112+
113+
1. It should show the following when the MCP Inspector is up and running:
114+
115+
```bash
116+
MCP Inspector is up and running at http://127.0.0.1:6274
117+
```
118+
119+
1. Open the above link in your browser.
120+
121+
1. For `Transport Type`, select `Streamable HTTP`.
122+
123+
1. For `URL`, type in `http://127.0.0.1:5000/mcp`.
124+
125+
1. Click the `Connect` button.
126+
127+
1. Click `List Tools` — you should see the `search_movies_by_actor`,
128+
`execute_cypher`, and `get_schema` tools. Select one and try it out: ask
129+
for Tom Hanks' movies, run an ad-hoc Cypher query, or fetch the graph
130+
schema.

‎docs/en/integrations/falkordb/source.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
title: "FalkorDB Source"
3+
linkTitle: "Source"
4+
type: docs
5+
weight: 1
6+
description: >
7+
FalkorDB is a low-latency, open source graph database built for GenAI workloads
8+
no_list: true
9+
---
10+
11+
## About
12+
13+
[FalkorDB][falkordb-docs] is a low-latency graph database that speaks the
14+
openCypher query language over the Redis protocol. A single FalkorDB instance
15+
can host many independent graphs, and its native vector and full-text indexes
16+
make it a popular knowledge-graph backend for GenAI applications.
17+
18+
The source connects to one instance and designates a default graph; tools can
19+
optionally target other graphs on the same instance.
20+
21+
[falkordb-docs]: https://docs.falkordb.com/
22+
23+
## Available Tools
24+
25+
{{< list-tools >}}
26+
27+
## Requirements
28+
29+
### Database User
30+
31+
FalkorDB instances without access control can be used with no credentials
32+
(e.g. a local `docker run -p 6379:6379 falkordb/falkordb` instance). For
33+
instances with authentication enabled, such as FalkorDB Cloud, provide the
34+
`username` and `password` fields, and enable `tls` for encrypted endpoints.
35+
36+
## Example
37+
38+
```yaml
39+
kind: source
40+
name: my-falkordb-source
41+
type: falkordb
42+
host: 127.0.0.1
43+
port: "6379"
44+
username: ${FALKORDB_USERNAME}
45+
password: ${FALKORDB_PASSWORD}
46+
graph: my_graph
47+
```
48+
49+
{{< notice tip >}}
50+
Use environment variable replacement with the format ${ENV_NAME}
51+
instead of hardcoding your secrets into the configuration file.
52+
{{< /notice >}}
53+
54+
## Reference
55+
56+
| **field** | **type** | **required** | **description** |
57+
|----------------|:--------:|:------------:|----------------------------------------------------------------------------------|
58+
| type | string | true | Must be "falkordb". |
59+
| host | string | true | Host of the FalkorDB instance (e.g. "127.0.0.1"). |
60+
| port | string | true | Port of the FalkorDB instance (e.g. "6379"). |
61+
| username | string | false | Name of the user to connect as, if authentication is enabled. |
62+
| password | string | false | Password of the user, if authentication is enabled. |
63+
| graph | string | true | Name of the default graph tools operate on (e.g. "my_graph"). |
64+
| queryTimeoutMs | int | false | Per-query timeout in milliseconds. No timeout when unset. |
65+
| tls.enabled | bool | false | Enable TLS for the connection. Defaults to false. |
66+
| tls.insecureSkipVerify | bool | false | Skip server certificate verification (not recommended). Defaults to false. |

‎docs/en/integrations/falkordb/tools/_index.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
---
2+
title: "Tools"
3+
weight: 2
4+
---

0 commit comments

Comments
 (0)