Add MCP server #39

flyrain · 2025-11-10T22:21:27Z

This PR is moved from apache/polaris#2980, per discussion here, https://lists.apache.org/thread/8w5n089mtsyd3mvv7j89h0h7nvvp7o4w.

cc @adam-christian-software

adam-christian-software

Absolutely fantastic work! 🚀

I put in some comments. Some are necessary, but a lot of them are nits. We can push a lot of these to the git issues and handle them from there post-merge.

mcp-server/README.md

adam-christian-software · 2025-11-11T18:03:48Z

mcp-server/polaris_mcp/tools/table.py

+        if not isinstance(body, dict):
+            raise ValueError(
+                "Create operations require a request body that matches the CreateTableRequest schema. See CreateTableRequest in "
+                "https://raw.githubusercontent.com/apache/polaris/apache-polaris-1.2.0-incubating/spec/generated/bundled-polaris-catalog-service.yaml"


We can file a GitHub issue here, but we are linking a specific version of the Apache Polaris interface. We could:

Modify this to a redirect to the most recent version

Have the user pass in an Polaris version

Have some way to communicate which version Polaris is and have the MCP Server pull in the right version of the entities

We will need to think through, as this is not the only place where MCP server is tied to particular Polaris server. A dynamic context switch for different Polaris server version may not be possible. I mentioned the version mapping in my another comments. WDYT?

Right now, I'd recommend you:

File a GitHub issue

Link this comment

Later, have a longer conversation on the Dev ML with multiple options. In my opinion, this is an "architecturally significant requirement," so there will be multiple perspectives. I don't want this sort of consensus building to block our users from trying out the first version, so I think we can defer this until later.

mcp-server/polaris_mcp/rest.py

mcp-server/polaris_mcp/server.py

mcp-server/polaris_mcp/tools/namespace.py

mcp-server/polaris_mcp/authorization.py

adam-christian-software

This PR looks good to me. I understand that we have a lot of filed issues to work on, but this looks good for a first version where we can iterate on. Thanks!

HonahX

This looks great! I left some comments from project management perspective but I do not think they should be blocker of this initial PR.

One thing we probably need is the github workflow to run unit tests

mcp-server/tests/test_namespace_tool.py

mcp-server/README.md

HonahX · 2025-11-14T01:30:42Z

mcp-server/pyproject.toml

+
+[project]
+name = "polaris-mcp"
+version = "0.9.0"


Curious, what's the plan for the package version. Is 1.0.0 the next version same as what polaris previously did?

I think so. 0.9.0 would server as a preview version before we move to 1.0.0. WDYT? cc @adam-christian-software

So, I think there are two things here:

The "how" we ship.

The "versioning" heuristics we should use.

For #1, @flyrain has filed an Issue ( #46 ) to investigate the packaging and publishing. Right now, I don't believe that we need to think about this since we can largely borrow the principles that we use for the Python CLI when we have completed that work.

For #2, I have assumed that we will use the typical semantic versioning approach (https://semver.org/). While that helps us determine when we do breaking changes and when we don't, it does not provide the entire guidance. SemVer states:

Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Version 1.0.0 defines the public API. The way in which the version number is incremented after this release is dependent on this public API and how it changes.

For this particular project, I would say that it makes sense for us to release first with 0.9.0 because this work is still very much in a prototype phase. We have several Git issues to tackle to firm up the solution. We should get those done after this PR and a lot of those items should be done before the first release.

This begs the question: When do we go from 0.X.0 to 1.0.0? For me, I would say a few things should happen:

We have one user who has used this work and given feedback.

We should not have any critical issues.

We should have good-enough unit & IT testing.

As this is a client of our Polaris server, we should nail down our compatibility story.

We should do a quick audit of any security issues.

We should have user-facing documentation on the Polaris Hugo site.

We should have all of the operational readiness items done - deployment processes, monitoring/observability, & upgrades/rollback processes.

Until we nail those 7 things, I wouldn't put this as a 1.0.0 project.

HonahX · 2025-11-14T01:36:54Z

mcp-server/pyproject.toml

+    "fastmcp>=2.13.0.2",
+    "urllib3>=1.25.3,<3.0.0",
+]
+


It will be good to add format and lint tools to this project, as those make collaboration easier.

precommit + ruff would be a good option: https://github.com/apache/polaris/blob/main/client/python/.pre-commit-config.yaml

We could create an issue and add that in a follow-up

Added. Thanks for the suggestion!

mcp-server/polaris_mcp/tools/principal_role.py

flyrain · 2025-11-14T18:21:31Z

Python github CI works well:

10s
Run uv run pre-commit run --all-files
[INFO] Initializing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Initializing environment for https://github.com/astral-sh/ruff-pre-commit.
[INFO] Installing environment for https://github.com/pre-commit/pre-commit-hooks.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
[INFO] Installing environment for https://github.com/astral-sh/ruff-pre-commit.
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
debug statements (python)................................................Passed
ruff check...............................................................Passed
ruff format..............................................................Passed
4s
Run uv run pytest
============================= test session starts ==============================
platform linux -- Python 3.12.12, pytest-9.0.1, pluggy-1.6.0
rootdir: /home/runner/work/polaris-tools/polaris-tools/mcp-server
configfile: pyproject.toml
plugins: anyio-4.11.0
collected 27 items

tests/test_namespace_tool.py ..                                          [  7%]
tests/test_rest_tool.py ...                                              [ 18%]
tests/test_server.py .............                                       [ 66%]
tests/test_table_tool.py .........                                       [100%]

============================== 27 passed in 2.21s ==============================

flyrain · 2025-11-14T18:25:29Z

This looks great! I left some comments from project management perspective but I do not think they should be blocker of this initial PR.

One thing we probably need is the github workflow to run unit tests

Thanks a lot for the review, @HonahX ! Added github CI for lint and unit tests. Please take another look.

HonahX

LGTM!

Add mcp server

c6f6fe7

flyrain requested review from HonahX, MonkeyCanCode, RussellSpitzer, adutra, ajantha-bhat, ashvina, collado-mike, dennishuo, dimas-b, ebyhr, eric-maynard, jackye1995, jbonofre, pingtimeout, singhpk234, snazy, takidau and vvcephei as code owners November 10, 2025 22:21

flyrain added 7 commits November 10, 2025 14:47

Add unit tests

e74dbf7

Add uv.lock

3f10793

Refactor

917d902

Add url-encoding

3ffdf8a

Add hint for table creation

f2ccbcf

Refactor

efbda2c

Add tests and fix the spliter

4a1eff4

adam-christian-software reviewed Nov 11, 2025

View reviewed changes

flyrain added 3 commits November 12, 2025 15:07

A clear message to construct nested namespaces

8daad6d

Allow MCP client to specify namespaces separated by dot

eb5effa

Resovle comments

240ad8b

flyrain added 2 commits November 12, 2025 15:46

Resovle comments

76ffac4

Resolve comments

8f6b039

This was referenced Nov 13, 2025

Configurable HTTP timeout for MCP server #44

Closed

Add throttling & retry logic for MCP http reqeust #45

Closed

Resolve comments

c7e4f98

This was referenced Nov 13, 2025

MCP Server improvments #46

Open

Configurable token buffer in MCP server #47

Closed

Add tests for all tools and authentication flows in MCP server #48

Open

Add structured logging in MCP server #49

Closed

flyrain added 2 commits November 12, 2025 18:07

Resolve comments

c5d75da

Resolve comments

0a239b7

adam-christian-software approved these changes Nov 13, 2025

View reviewed changes

flyrain mentioned this pull request Nov 13, 2025

Better context and version handing between Polaris and MCP server #50

Open

HonahX reviewed Nov 14, 2025

View reviewed changes

flyrain added 6 commits November 13, 2025 22:14

Resolve comments

5743e93

Use pytest

c2741f6

Add lint

24cc759

Add lint

578da2f

Add Github workflow for mcp-server

6c7e912

Add Github workflow for mcp-server

e14f59a

Add Github workflow for mcp-server

c23b422

HonahX approved these changes Nov 14, 2025

View reviewed changes

flyrain merged commit 8d3997a into apache:main Nov 14, 2025
9 checks passed

Add MCP server #39

Add MCP server #39

Uh oh!

Conversation

flyrain commented Nov 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

adam-christian-software left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

adam-christian-software Nov 13, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

adam-christian-software left a comment

Choose a reason for hiding this comment

Uh oh!

HonahX left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

flyrain commented Nov 14, 2025

Uh oh!

flyrain commented Nov 14, 2025

Uh oh!

HonahX left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

flyrain commented Nov 10, 2025 •

edited

Loading

adam-christian-software left a comment •

edited

Loading

adam-christian-software Nov 13, 2025 •

edited

Loading

HonahX left a comment •

edited

Loading