Add JDBC MCP stdio configuration

Author: codeboyzhou

.gitignore

@@ -7,6 +7,3 @@
 
 # Maven build files
 target/
-
-# Test files
-*.db

README.md

@@ -17,28 +17,153 @@ The [Model Context Protocol (MCP)](https://modelcontextprotocol.io) lets servers
 
 ## JDBC Server
 
-The JDBC example currently includes an annotated-sdk implementation backed by SQLite.
+The JDBC example includes an annotated-sdk implementation backed by a JDBC connection.
+The packaged server starts in STDIO mode by default.
 
 Implemented resource:
 
-- `db://schema` - Returns database product name and version as JSON
+- `db://schema` - Returns database product/version plus table and column metadata as JSON
 
-Default database configuration:
+JDBC configuration for the MCP server process:
 
-- `JDBC_URL` defaults to `jdbc:sqlite:./test.db`
+- `JDBC_URL` is required
 - `JDBC_USERNAME` is optional
 - `JDBC_PASSWORD` is optional
 
-Run the server:
+Bundled sample database:
 
-```powershell
-.\mvnw.cmd -pl mcp-server-jdbc/mcp-server-jdbc-annotated-sdk -am package
-java -jar mcp-server-jdbc\mcp-server-jdbc-annotated-sdk\target\mcp-server-jdbc-annotated-sdk-1.0.0.jar
+- `mcp-server-jdbc/mcp-server-jdbc-common/src/test/resources/sqlite3.db`
+
+Build the MCP server jar first:
+
+```bash
+./mvnw -pl mcp-server-jdbc/mcp-server-jdbc-annotated-sdk -am package
+```
+
+On Windows PowerShell, use `.\mvnw.cmd` instead of `./mvnw`.
+
+The jar is created at:
+
+- `mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/target/mcp-server-jdbc-annotated-sdk.jar`
+
+Use these paths in the examples below:
+
+- `<repo>` - absolute path to this repository
+- `<jar>` - `<repo>/mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/target/mcp-server-jdbc-annotated-sdk.jar`
+- `<sqlite3.db>` - `<repo>/mcp-server-jdbc/mcp-server-jdbc-common/src/test/resources/sqlite3.db`
+
+For Windows paths in JSON/TOML, prefer forward slashes, for example `C:/Users/me/code/mcp-java-sdk-examples/...`.
+
+### MCP Inspector
+
+Start Inspector with the JDBC server as a STDIO server:
+
+```bash
+npx @modelcontextprotocol/inspector -e JDBC_URL=jdbc:sqlite:<sqlite3.db> -- java -jar <jar>
+```
+
+Open the Inspector URL printed in the terminal, then browse the `db://schema` resource.
+
+### Claude Desktop
+
+Add the server to Claude Desktop MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "jdbc-mcp-server": {
+      "command": "java",
+      "args": ["-jar", "<jar>"],
+      "env": {
+        "JDBC_URL": "jdbc:sqlite:<sqlite3.db>"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop, then browse the `db://schema` resource from the MCP tools/resources panel.
+
+### Codex
+
+Add the server with the Codex CLI:
+
+```bash
+codex mcp add jdbc-mcp-server --env JDBC_URL=jdbc:sqlite:<sqlite3.db> -- java -jar <jar>
+```
+
+Or add it to `~/.codex/config.toml` or a trusted project `.codex/config.toml`:
+
+```toml
+[mcp_servers.jdbc-mcp-server]
+command = "java"
+args = ["-jar", "<jar>"]
+
+[mcp_servers.jdbc-mcp-server.env]
+JDBC_URL = "jdbc:sqlite:<sqlite3.db>"
+```
+
+### Cursor
+
+Add this server in Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "jdbc-mcp-server": {
+      "command": "java",
+      "args": ["-jar", "<jar>"],
+      "env": {
+        "JDBC_URL": "jdbc:sqlite:<sqlite3.db>"
+      }
+    }
+  }
+}
+```
+
+### Cline
+
+Open Cline MCP settings and add:
+
+```json
+{
+  "mcpServers": {
+    "jdbc-mcp-server": {
+      "command": "java",
+      "args": ["-jar", "<jar>"],
+      "env": {
+        "JDBC_URL": "jdbc:sqlite:<sqlite3.db>"
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+Create or update `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "jdbc-mcp-server": {
+      "type": "stdio",
+      "command": "java",
+      "args": ["-jar", "<jar>"],
+      "env": {
+        "JDBC_URL": "jdbc:sqlite:<sqlite3.db>"
+      }
+    }
+  }
+}
 ```
 
-Run with a custom SQLite database:
+For databases that require credentials, add them to the MCP server environment:
 
-```powershell
-$env:JDBC_URL = "jdbc:sqlite:C:\path\to\database.db"
-java -jar mcp-server-jdbc\mcp-server-jdbc-annotated-sdk\target\mcp-server-jdbc-annotated-sdk-1.0.0.jar
+```json
+"env": {
+  "JDBC_URL": "jdbc:postgresql://localhost:5432/example",
+  "JDBC_USERNAME": "user",
+  "JDBC_PASSWORD": "password"
+}
 ```

mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/pom.xml

@@ -31,6 +31,7 @@
     </dependencies>
 
     <build>
+        <finalName>${project.artifactId}</finalName>
         <plugins>
             <plugin>
                 <groupId>org.apache.maven.plugins</groupId>
@@ -40,7 +41,7 @@
                     <createDependencyReducedPom>false</createDependencyReducedPom>
                     <transformers>
                         <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
-                            <mainClass>com.github.thought2code.mcp.server.jdbc.annotated.JdbcMcpServer</mainClass>
+                            <mainClass>com.github.thought2code.mcp.server.jdbc.annotated.JdbcMcpStdioServer</mainClass>
                         </transformer>
                     </transformers>
                 </configuration>

…server/jdbc/annotated/JdbcMcpServer.java …r/jdbc/annotated/JdbcMcpStdioServer.javamcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/java/com/github/thought2code/mcp/server/jdbc/annotated/JdbcMcpServer.java renamed to mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/java/com/github/thought2code/mcp/server/jdbc/annotated/JdbcMcpStdioServer.java mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/java/com/github/thought2code/mcp/server/jdbc/annotated/JdbcMcpServer.java renamed to mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/java/com/github/thought2code/mcp/server/jdbc/annotated/JdbcMcpStdioServer.java

@@ -4,8 +4,8 @@
 import com.github.thought2code.mcp.annotated.annotation.McpServerApplication;
 
 @McpServerApplication
-public class JdbcMcpServer {
+public class JdbcMcpStdioServer {
   public static void main(String[] args) {
-    McpApplication.run(JdbcMcpServer.class, args);
+    McpApplication.run(JdbcMcpStdioServer.class, args, "mcp-server-stdio-mode.yml");
   }
 }

mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/java/com/github/thought2code/mcp/server/jdbc/annotated/JdbcMcpStreamableHttpServer.java

@@ -0,0 +1,12 @@
+package com.github.thought2code.mcp.server.jdbc.annotated;
+
+import com.github.thought2code.mcp.annotated.McpApplication;
+import com.github.thought2code.mcp.annotated.annotation.McpServerApplication;
+
+@McpServerApplication
+public class JdbcMcpStreamableHttpServer {
+  public static void main(String[] args) {
+    McpApplication.run(
+        JdbcMcpStreamableHttpServer.class, args, "mcp-server-streamable-http-mode.yml");
+  }
+}

mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/java/com/github/thought2code/mcp/server/jdbc/annotated/McpServerResources.java

@@ -2,8 +2,9 @@
 
 import com.github.thought2code.mcp.annotated.annotation.McpResource;
 import com.github.thought2code.mcp.annotated.enums.MimeType;
-import com.github.thought2code.mcp.server.jdbc.common.DatabaseSchema;
-import com.github.thought2code.mcp.server.jdbc.common.datasource.DataSourceFactory;
+import com.github.thought2code.mcp.server.jdbc.common.datasource.DriverManagerDataSource;
+import com.github.thought2code.mcp.server.jdbc.common.schema.DatabaseSchema;
+import com.github.thought2code.mcp.server.jdbc.common.schema.JdbcSchemaReader;
 import lombok.extern.slf4j.Slf4j;
 
 @Slf4j
@@ -15,7 +16,7 @@ public class McpServerResources {
       mimeType = MimeType.APPLICATION_JSON)
   public DatabaseSchema getDatabaseSchema() {
     try {
-      return DataSourceFactory.getDataSource().getDatabaseSchema();
+      return new JdbcSchemaReader().read(DriverManagerDataSource.fromEnv());
     } catch (Exception e) {
       log.error("Failed to get database schema", e);
       throw new IllegalStateException("Failed to get database schema", e);

mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/resources/logback.xml

@@ -1,7 +1,9 @@
 <?xml version="1.0" encoding="UTF-8"?>
 <configuration>
 
-    <property name="PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n"/>
+    <property name="LOG_DIR" value="${LOG_DIR:-logs}"/>
+    <property name="LOG_FILE" value="${LOG_FILE:-${LOG_DIR}/jdbc-mcp-server.log}"/>
+    <property name="PATTERN" value="%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%-5level] %logger{36} - %msg%n"/>
 
     <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
         <target>System.err</target>
@@ -11,11 +13,24 @@
         </encoder>
     </appender>
 
+    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
+        <file>${LOG_FILE}</file>
+        <encoder>
+            <pattern>${PATTERN}</pattern>
+            <charset>UTF-8</charset>
+        </encoder>
+        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
+            <fileNamePattern>${LOG_FILE}.%d{yyyy-MM-dd}.log</fileNamePattern>
+            <maxHistory>14</maxHistory>
+        </rollingPolicy>
+    </appender>
+
     <logger name="org.eclipse.jetty" level="WARN"/>
     <logger name="io.modelcontextprotocol" level="WARN"/>
 
-    <root level="WARN">
+    <root level="DEBUG">
         <appender-ref ref="CONSOLE"/>
+        <appender-ref ref="FILE"/>
     </root>
 
 </configuration>

mcp-server-jdbc/mcp-server-jdbc-annotated-sdk/src/main/resources/mcp-server-stdio-mode.yml

@@ -0,0 +1,17 @@
+enabled: true
+mode: STDIO
+name: jdbc-mcp-server
+version: 1.0.0
+type: SYNC
+instructions: You are a helpful AI assistant that can access a database and perform operations on it
+request-timeout: 20000
+capabilities:
+  resource: true
+  subscribe-resource: true
+  prompt: false
+  tool: false
+  completion: false
+change-notification:
+  resource: true
+  prompt: false
+  tool: false