mcp/examples: add PostgreSQL MCP server example #70

gk16 · 2025-06-29T00:21:19Z

Add standalone PostgreSQL MCP server example with development environment and tooling. This implementation provides read-only database access, schema introspection, and query capabilities while maintaining clean dependency separation from the main SDK.

Motivation and Context

This is part of #33. This PR adds example of implementing mcp on PostgreSQL from https://modelcontextprotocol.io/examples.
The PR provides a production-ready PostgreSQL MCP server example with proper deployment options, testing, and development tooling.

How Has This Been Tested?

17 test cases, including unit tests, integration tests, and edge case handling
Full docker-compose setup with PostgreSQL database and sample data
Tested against live PostgreSQL with sample schema (users, products, orders tables)

Breaking Changes

No Breaking Changes: This is purely additive - a new example in a separate subproject

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Architecture Decisions

Independent Module: Created examples/postgres/go.mod for this example
Read-Only Safety: All database operations use read-only transactions to prevent accidental data modification

Files Added

main.go - PostgreSQL MCP server implementation with schema introspection and query tools
main_test.go - Comprehensive test suite with mock database testing
go.mod/go.sum - Independent module definition with local SDK reference
Dockerfile - Multi-stage build for production deployment
docker-compose.yml - Complete development environment with PostgreSQL
init.sql - Sample database schema and data for testing
Makefile - Build automation and development workflow
demo.sh - Interactive demonstration script
README.md - Complete documentation following Python server format
.env.example - Configuration template
.gitignore - Proper exclusions for Go and Docker artifacts

Development Experience

Quick Start: make dev sets up complete environment
Multiple Run Modes: stdio (default) and HTTP (debugging) modes

MCP Features Implemented

Resources: Dynamic table discovery with schema information
Tools: Read-only SQL query execution with transaction safety
Error Handling: Proper MCP error responses and comprehensive error coverage
Resource URIs: Standard format postgres://host/table/schema

This implementation serves as a reference for building production MCP servers while maintaining clean project architecture.

jba · 2025-06-30T11:49:59Z

Thanks for this large contribution. It's a lot of work, and we appreciate that. It's cool that you have a complete implementation, with a Makefile, shell scripts, Dockerfile, and so on.

This is definitely worth living somewhere. I'm just not sure it should live in this repo. There is a lot of code to maintain. What if we get a bug report against the Dockerfile or docker compose config? Or some bug about a runtime failure in a particular installation? I don't know if the maintainers of this repo are up to that sort of commitment.

We're going to think about this and get back to you.

/cc @findleyr @samthanawalla

gk16 · 2025-07-01T21:08:27Z

Thanks for this large contribution. It's a lot of work, and we appreciate that. It's cool that you have a complete implementation, with a Makefile, shell scripts, Dockerfile, and so on.

This is definitely worth living somewhere. I'm just not sure it should live in this repo. There is a lot of code to maintain. What if we get a bug report against the Dockerfile or docker compose config? Or some bug about a runtime failure in a particular installation? I don't know if the maintainers of this repo are up to that sort of commitment.

We're going to think about this and get back to you.

/cc @findleyr @samthanawalla

Thanks a lot for your nice words.
Yes, I agree. As more complete golang examples coming in, it would be nice to have a seperate repo to host them, like https://github.com/modelcontextprotocol/servers (they are mostly Python and TS examples)

examples/postgres/main.go

examples/postgres/main_test.go

jba · 2025-07-04T15:46:27Z

The modelcontextprotocol/servers repo is not going to happen.

Here's what we'd like to do:

Accept the Go code into this repo.
You should host all the code, include scripts and docker config, in your own repo, and add a link here to it.

One concern is that the additional non-Go code is a maintenance burden for us. We are also concerned about security.

You can leave all the other code here for now if it helps you test my suggested changes.

Thanks again for this great piece of work!

gk16 · 2025-07-10T08:21:40Z

The modelcontextprotocol/servers repo is not going to happen.

Here's what we'd like to do:

Accept the Go code into this repo.

You should host all the code, include scripts and docker config, in your own repo, and add a link here to it.

One concern is that the additional non-Go code is a maintenance burden for us. We are also concerned about security.

You can leave all the other code here for now if it helps you test my suggested changes.

Thanks again for this great piece of work!

Thank a lot for your review. I did learn a lot from it.

I have addressed the comments. Please take another look when you have a chance.

As for the all other code, do you mean I can keep main.go, postgres_server.go, postgres_server_test.go, and README.md these 4 files here and move all other files into a seperate repo, right?

jba · 2025-07-10T13:12:04Z

As for the all other code, do you mean I can keep main.go, postgres_server.go, postgres_server_test.go, and README.md these 4 files here and move all other files into a seperate repo, right?

Yes.

jba

Looking good. Proceed with removing the non-Go files.

Leave the README as it is for your own repo, but for this repo, leave an edited version that links to your repo.

jba · 2025-07-10T13:14:14Z

examples/postgres/postgres_server.go

+	if trimmedPath != "" {
+		pathParts = strings.Split(trimmedPath, "/")
+		// Filter out empty parts that might result from consecutive slashes
+		var filteredParts []string


Use slices.DeleteFunc.

jba · 2025-07-10T13:17:12Z

examples/postgres/postgres_server_test.go

+		{
+			name:          "edge case - table name with special characters",
+			resourceURI:   "postgres://localhost:5432/testdb/test-table_123/schema",
+			expectedTable: "test-table_123",


Add a test with "///" to test removal of empty parts.

feat(examples): add PostgreSQL MCP server as independent subproject

a344a4e

gk16 marked this pull request as ready for review June 29, 2025 00:22

gk16 mentioned this pull request Jun 29, 2025

Tracking issue: adding examples #33

Open

jba mentioned this pull request Jul 1, 2025

add to servers repo #52

Open

jba requested changes Jul 4, 2025

View reviewed changes

gk16 added 3 commits July 6, 2025 10:18

Merge branch 'main' into add-postgresql-example

8c47301

Added postgres_server.go and optimized code

b037d1c

format the code

92bfa16

gk16 requested a review from jba July 10, 2025 08:22

jba requested changes Jul 10, 2025

View reviewed changes

jba mentioned this pull request Jul 23, 2025

Would you accept an examples/ addition with a practical MCP server? #165

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

mcp/examples: add PostgreSQL MCP server example #70

mcp/examples: add PostgreSQL MCP server example #70

Uh oh!

gk16 commented Jun 29, 2025

Uh oh!

jba commented Jun 30, 2025

Uh oh!

gk16 commented Jul 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jba commented Jul 4, 2025

Uh oh!

gk16 commented Jul 10, 2025

Uh oh!

jba commented Jul 10, 2025

Uh oh!

jba left a comment

Uh oh!

jba Jul 10, 2025

Uh oh!

jba Jul 10, 2025

Uh oh!

Uh oh!

mcp/examples: add PostgreSQL MCP server example #70

Are you sure you want to change the base?

mcp/examples: add PostgreSQL MCP server example #70

Uh oh!

Conversation

gk16 commented Jun 29, 2025

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Architecture Decisions

Files Added

Development Experience

MCP Features Implemented

Uh oh!

jba commented Jun 30, 2025

Uh oh!

gk16 commented Jul 1, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

jba commented Jul 4, 2025

Uh oh!

gk16 commented Jul 10, 2025

Uh oh!

jba commented Jul 10, 2025

Uh oh!

jba left a comment

Choose a reason for hiding this comment

Uh oh!

jba Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

jba Jul 10, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!