GraphJin: One Governed Graph for AI Agents
A governed graph that gives AI agents secure access to databases, files, code, and APIs via GraphQL and MCP.
Evidence shows: SECURITY.md details least-privilege principles in source mode, including default blocked writes/deletes, account/owner scoping, system root access matrix, and internal reserved role. User confirmation: preview/apply two-step config updates exist, but no explicit user confirmation mechanism. Data flow transparency: documentation describes data flow and audit logs, but lacks full execution ledger details. Sensitive data handling: documentation mentions redaction of identity fields, not storing raw JWTs/secrets, but no implementation details. Dependency security: package.json lists only tar dependency, no dependency audit or vulnerability scan evidence. External effects: documentation describes access control for external systems (databases, files, APIs), but no rollback mechanism. Rollback: config updates have preview/apply, but no rollback for data operations. Source attribution: publisher identity unverified, but documentation provides author and maintainer info. Deductions: insufficient evidence for user confirmation, rollback, dependency security.
Evidence shows: README and SECURITY.md are consistent on modes, access control, system roots. Dependency availability: multiple installation methods (npm, Homebrew, Scoop, Docker), but no dependency availability guarantee. Failure messages: documentation mentions error returns, but no specific failure message examples. Deduction: insufficient evidence for failure messages.
Evidence shows: README describes multiple use cases (databases, files, code, APIs) and provides several demos. Capability boundaries: documentation clearly distinguishes modes (dev/prod/agentic) and access control. Trigger precision: MCP tools and GraphQL queries are clearly described. Environment fit: supports multiple databases and deployment methods. Deduction: no major deductions.
Evidence shows: README is well-structured with installation, usage, configuration, security sections. Install notes are detailed. Naming stability: version numbers clear, but no naming conventions. Examples and FAQ: multiple examples provided, but no FAQ. Known limitations: documentation mentions some limitations (e.g., prod mode disables agentic surface), but not comprehensive. License: Apache-2.0 license file complete. Versioning changelog: no CHANGELOG, but version in package.json. Maintenance responsibility: documentation provides author and maintainer info. Deductions: missing FAQ and comprehensive known limitations.
Evidence shows: Output usability: multiple output formats (GraphQL, REST, MCP). Marginal value: unique features (e.g., CodeSQL, agent). Cost-benefit: documentation claims high performance, but no benchmarks. Deduction: insufficient evidence for cost-benefit.
Evidence shows: Claim traceability: README claims align with SECURITY.md and code. Cross-source corroboration: documentation consistent, but lacks independent verification. Fact-inference separation: documentation distinguishes feature descriptions and design intent. Deduction: insufficient cross-source corroboration.
- Publisher identity is unverified; treat as unknown and do not rely on brand trust.
- Static review cannot verify actual runtime behavior; all security claims need independent testing before deployment.
- Dependency security evidence is insufficient; recommend checking for dependency vulnerabilities.
- Lack of user confirmation and rollback mechanisms; proceed with caution.
What does this agent do, and when should you use it?
GraphJin is a compiler and runtime that unifies a company's existing systems—databases, warehouses, files, source code, workflows, metadata, and security policy—into a single governed graph, exposed through GraphQL and MCP for AI agents. Agents discover before acting, validate queries, execute approved operations, and observe runtime status, with every answer checked against an execution ledger. It also serves as a high-performance GraphQL-to-database compiler, Go library, standalone API service, REST/OpenAPI gateway, and real-time subscription server. It supports a wide range of databases (PostgreSQL, MySQL, MongoDB, SQLite, Oracle, MSSQL, Snowflake, Redshift, BigQuery, Cassandra, etc.), file systems, and code indexing. A built-in server-side agent accepts an instruction and returns typed, evidence-backed answers.
GraphJin automatically reads database schemas, discovers relationships from foreign keys, exposes built-in gj_* system tables (e.g., gj_catalog, gj_code, gj_security, gj_runtime), and compiles GraphQL queries into optimized SQL. It guides AI agents via MCP tools like query_catalog, graphql_help, and validate_where_clause to discover before acting, and restricts operations through query allow-lists, read-only boundaries, and policy-aware tools. It also indexes source code with CodeSQL, managing syntax trees and database references in a SQLite database. The built-in server-side agent processes instructions via POST /api/v1/agent, returning structured answers. It supports real-time subscriptions, filesystem tables (local, S3, GCS), file uploads, and Apollo Federation v2.
- Developers can instantly create a GraphQL API over existing databases without writing resolvers, using GraphJin as a standalone service or Go library.
- AI coding assistants like Claude Code or Codex connect via MCP to safely query and mutate production databases with governance.
- Data analysts use natural language through the server-side agent to generate queries and receive evidence-backed results.
- Operations teams enforce query allow-lists and read-only modes to control AI write access to production systems.
- Development teams use CodeSQL to index source code and let agents answer questions like which handlers touch customer invoices.
What are this agent's strengths and limitations?
- Unified governance: one graph over multiple systems, so agents don't need raw credentials and risk is reduced.
- High-performance query compilation: compiles GraphQL to a single optimized SQL, avoiding N+1 problems.
- Rich security mechanisms: query allow-lists, read-only boundaries, row-level security, policy-aware MCP tools, and execution ledger for auditability.
- Built-in server-side agent: one instruction returns evidence-backed answers, simplifying integration.
- Wide database and data source support: includes major relational, NoSQL, warehouses, and file systems.
- May be overkill for small projects: configuration and learning curve suited for enterprise scenarios.
- Some databases (Redshift, BigQuery) have experimental or incomplete support.
- Subscription support depends on database dialect; some (Cassandra) only support polling.
- Server-side agent requires a model API key and works best with code-generation-capable models.
- Migration from legacy database mode to source mode requires configuration changes and a learning curve.
How do you install or deploy this agent?
Install GraphJin via npm (npm install -g graphjin), Homebrew (brew install dosco/graphjin/graphjin), Scoop on Windows, .deb/.rpm packages for Linux, or Docker (docker pull dosco/graphjin). Then create a new app with graphjin serve new my-app and start it with graphjin serve --path ./my-app.
How do you use this agent?
After starting the service, add GraphJin to an AI client: for Claude Code, run graphjin mcp add claude http://localhost:8080; for Codex, run codex mcp add graphjin --url http://localhost:8080/api/v1/mcp. Then ask natural language questions like 'What tables are in the database?' and the client will use MCP tools to respond. Alternatively, call the GraphQL endpoint (POST /api/v1/graphql) directly or the server-side agent (POST /api/v1/agent).