choice of tech stack

[JohnRDOrazio]

Ok team, given your current experience with MCP, let's choose a tech stack together. I created a sample README just to start presenting generally what this project is, but we can perfect it over time.

I found NetworkChuck's youtube video to be quite helpful: https://www.youtube.com/watch?v=GuTcle5edjk.

In that video he asks Claude to create an MCP server for him, and Claude chooses Python. Do you all have some familiarity with Python? Can we proceed with this approach?

I also found this article: Choosing the Right Tech Stack for Building MCP Servers. From the three options that the author compares between (Python, NodeJS and Java) it seems to me like Python is a decent choice:

Python: The Swiss Army Knife of AI

• Strengths: Dominates the AI/ML world, massive library support (PyTorch, LangChain, Hugging Face).
• Best for: MCP servers tightly coupled with AI workflows, data analysis, or ML models.
• Example: Exposing a Pandas-based analytics tool as an MCP endpoint.
• Analogy: Like a Swiss Army Knife — always has the right attachment for the job.

But I'm open to hearing your own thoughts on this too.

In any case the Swagger documentation for the Liturgical Calendar API can be found here: https://litcal.johnromanodorazio.com/dist/.

We don't need to wire up any of the PUT/PATCH/DELETE methods for the MCP server for now, because they're not yet protected behind authentication (which they should be), and in fact they are not even complete yet, I need to do some more work on them but I figured I would complete them after JWT authentication is built into the API.

So we can just hook up some tool calls that integrate with the GET/POST methods on the various endpoints. In this API, GET and POST are both read methods. POST does not create or update anything, it simply allows to pass parameters in the body of the request rather than in the URL.

[RandyDanielson]

We may want to create a product requirement document (PRD) for this first, and then that can be used to vibe code the starting structure of the project. I've had good results doing this with my other projects. Happy to start something like that today and we can iterate over it.

[JohnRDOrazio]

I just pushed a https://github.com/CatholicOS/liturgical-calendar-mcp/tree/docker-implementation branch, to show what I have so far. The claude-instructions.md file is what I pasted into the Claude chat interface, along with:

You are an expert MCP (Model Context Protocol) server developer. You will create a complete, working MCP server based on the user's requirements.

I followed Network Chuck's template at https://github.com/theNetworkChuck/docker-mcp-tutorial/blob/main/mcp-builder-prompt/mcp-builder-prompt.md, with a couple adapatations.

For sure, the tool calls should be thought out better.

In any case, I added some minimal instructions in the README for how to add the tool to the Docker MCP Tool catalog, and have it seen by an agent such as Claude Desktop. The instructions in Network Chuck's documentation didn't exactly work, so I had to fix a few things up until I got it to work, for example:

• seems that Docker MCP Toolkit only reads the %USERPROFILE%\.docker\mcp\catalogs\docker-mcp.yaml catalog, and no other catalog files such as the custom.yaml suggested in the documentation
• nothing needs to be added to %APPDATA%\Claude\claude_desktop_config.json in the more recent versions, new tools from the Docker MCP Toolkit will be picked up automatically when it has a structure like this:

  {
      "mcpServers": {
          "MCP_DOCKER": {
              "command": "docker",
              "args": [
                  "mcp",
                  "gateway",
                  "run"
              ],
              "env": {
                  "LOCALAPPDATA": "C:\\Users\\[user]\\AppData\\Local",
                  "ProgramData": "C:\\ProgramData",
                  "ProgramFiles": "C:\\Program Files"
              }
          }
      }
  }

[JohnRDOrazio]

I'm seeing the tool methods in Claude Desktop now, but I'm not getting results when asking anything about the liturgical calendar, which could be a couple things:

• responses are too long and Claude Desktop can't handle it
• the decorated @mcp.tool methods have some issues that need to be sorted out

I created a file test_mcp.py just to see if we can get a tool list response from the MCP server with python test_mcp.py | python litcal_server.py. It seemed to have worked last night, now I'm seeing some errors, and perhaps because I've cleaned up litcal_server.py somewhat.

[JohnRDOrazio]

In any case, if you have a good approach to generating an initial project, please go ahead, you can create and push a branch, and we can evaluate which one is more promising.

[JohnRDOrazio]

I fixed the test_mcp.py, I had tried adding a pretty-print but that doesn't pretty print the JSON output, it pretty-prints the rpc message sent to the server, which is not allowed. I fixed by removing the pretty-print from there and adding it to the command line call itself by piping output to jq, which by default pretty-prints the JSON output. I added this info to the README under "local testing".

[rudolphh]

The article does point out something that had me wondering about the use-cases for this project: "Python for AI-heavy cases, Node.js for integrations." Would this be AI-heavy, or perhaps more for integrations? If this is going to scale into something that does more than just act as a facilitator for models (e.g., server-side generation or data pipelines, basically any server smarts), then Python would be best but strictly for tooling, Node would do the same and maybe save time for prototyping. I'm more comfortable with JS but hopefully could contribute either way.

[JohnRDOrazio]

It is also true that Python has broken a number of things over the years too, but it does have a wide support community and usually is fairly quick in remediating and fixing anything that's broken. So I don't know, either way.

[rudolphh]

Good news is we're out of the wild-west Node days (I can sympathize with you) and in LTS now. That said, I'm game for brushing up my Python game.

[jamestejada]

Publishing as a node package would allow users to use the MCP server with npx without having to install anything other than the regular dependencies. On the Python side, there is the newer uv package manager (it has uvx that I believe does the same thing) but I haven't tried using it for an MCP yet. I have only done direct uv run calls for local repositories.

[JohnRDOrazio]

I've seen uv popping up here and there, but I haven't used it yet. Is there any advantage over python virtual environments? Does uv make its own virtual environment?

[jamestejada]

I really like uv, and I've started converting some of my old projects to use it. I used to create helper scripts that would start the Python virtual environment, run the script and deactivate. uv handles all of that and more. The biggest thing that I noticed is how fast it installs dependencies compared to pip. Depending on the library it's almost instant. You can also install different versions of Python pretty easily.

Once my pyproject.toml file is defined (instead of the using a requirements.txt file), I just have to type uv run main.py and it will automatically create the virtual environment, install any needed dependencies, run the script, and deactivate the virtual environment. There's even a uv add command if you just want to add a dependency from the command line. If you used cargo with the rust ecosystem, it feels a lot like that (It's written in rust by the way). I'm sure there's more features that I just haven't discovered yet.

[JohnRDOrazio]

I got the list_available_calendars tool call to work! Updated the branch with the latest working code. This is so cool:

I tested the tool call with a command line script test_mcp_list_available_calendars.py which I have checked into the repository. Once it was working well in the command line, I rebuilt the docker image, closed and opened Claude Desktop, and voilà beautiful results!

[rudolphh]

Seeing this result makes me think we can move forward with this approach. I just need to clean up and test each of the tool calls, to make sure they don't contain any errors. Have either of you attempted another approach in the meantime? If not, I can start merging this branch to main, and we can work from here. @RandyDanielson @rudolphh

I did attempt a typescript version just to make sure I understood network chuck approach. also cut out the middle-man (docker/mcp toolkit) and just changed claude desktop config (and added to vscode mcp.json) to use node/python directly. of course for distribution as a service docker would still be good, but for running locally it just removes a step. everything works. very cool.

Also learning how structured output (JSON) should maybe be priority if available to models as opposed to something more human readable; and simply adding metadata if it helps in understanding. Maybe add a parameter to return structured JSON instead of formatted text. The date format (US vs IT from my testing) is the only inconsistency I've found in the api (timestamp vs ISO string), but maybe you were addressing that earlier.

[JohnRDOrazio]

In the latest updates to the API I have refactored the date parameter from a Unix timestamp in seconds (which is typical of PHP) to an RFC 3339 formatted date-time string (where the time will always be midnight, as the liturgical events are "all-day" events). This solves a couple issues:

• in javascript timestamps are typically in milliseconds, compared the PHP where they typically in seconds, so it can get confusing to juggle back and forth according to which language is processing the data; a date-time string solves this completely
• in order to instantiate a Date object from a timestamp in javascript, where there is no timezone information, you would have to ensure the timezone is set to UTC; using a date-time string with UTC timezone solves this.

Is this what you were referring to, the date property for each liturgical event in the API response?

When it comes to output from the MCP server to the LLM, it is in my understanding that they speak to each other through JSON-RPC, which I am learning about only now. From NetworkChuck's examples, he specifically instructs Claude to produce tool call methods that only ever respond with strings. I'm studying up on the JSON-RPC spec to understand what the responses can actually look like. We can turn this into an issue, and work on it there.

[JohnRDOrazio]

And when I saw from NetworkChuck's video how streamlined the Docker MCP Toolkit is, I figured it would be a good and maintainable approach, of course for eventual distribution but even during development it's not very complicated either, you don't have to run any Docker containers, Docker takes care of spinning up the container on demand, so all that needs to be done is to build the Docker image. Which is required every time a change is made that needs to be tested. If there is a way to achieve an MCP server in development without the Docker MCP Toolkit middleman, please do outline the approach, and it can perhaps make the development process a little quicker. Let me open a wiki on the repository and feel free to document any other approaches. If you get a working Typescript example, we can perhaps even create a new repository for the Typescript approach, I'm sure many developers today would find that very appealing.

[rudolphh]

In the latest updates to the API I have refactored the date parameter from a Unix timestamp in seconds (which is typical of PHP) to an RFC 3339 formatted date-time string (where the time will always be midnight, as the liturgical events are "all-day" events). This solves a couple issues:

• in javascript timestamps are typically in milliseconds, compared the PHP where they typically in seconds, so it can get confusing to juggle back and forth according to which language is processing the data; a date-time string solves this completely
• in order to instantiate a Date object from a timestamp in javascript, where there is no timezone information, you would have to ensure the timezone is set to UTC; using a date-time string with UTC timezone solves this.

Is this what you were referring to, the date property for each liturgical event in the API response?

When it comes to output from the MCP server to the LLM, it is in my understanding that they speak to each other through JSON-RPC, which I am learning about only now. From NetworkChuck's examples, he specifically instructs Claude to produce tool call methods that only ever respond with strings. I'm studying up on the JSON-RPC spec to understand what the responses can actually look like. We can turn this into an issue, and work on it there.

yeah the date property.

and yes while true that its fine how the responses look, if it does have to do some programmatic filtering (e.g. "find all memorials in October") it helps because it doesn't seem as though the API has this level of granularity yet.

[rudolphh]

And when I saw from NetworkChuck's video how streamlined the Docker MCP Toolkit is, I figured it would be a good and maintainable approach, of course for eventual distribution but even during development it's not very complicated either, you don't have to run any Docker containers, Docker takes care of spinning up the container on demand, so all that needs to be done is to build the Docker image. Which is required every time a change is made that needs to be tested. If there is a way to achieve an MCP server in development without the Docker MCP Toolkit middleman, please do outline the approach, and it can perhaps make the development process a little quicker. Let me open a wiki on the repository and feel free to document any other approaches. If you get a working Typescript example, we can perhaps even create a new repository for the Typescript approach, I'm sure many developers today would find that very appealing.

I outlined an approach in a separate markdown and linked in the README, including the vscode workspace file, what is the workflow for contributors? Can I be added or external workflow (e.g. fork and PR)?

[RandyDanielson]

Pushed a very minor update to the .gitignore file to include Visual Studio specific entries.
Will look at this this evening.
Fr. @JohnRDOrazio please do push this to main so we can fork off of it.
Fantastic progress so far!

[JohnRDOrazio]

Done!

Are the recommended vscode extensions not useful? I checked in the vscode folder figuring it would allow us to have some common toolsets to work with.

[RandyDanielson]

It may be my professional career, but I have only had problems with sharing any of these files :)

[JohnRDOrazio]

Do you have any preferences when it comes to linting? I'm looking into implementing flake8 and possibly black in a requirements-dev.txt, but I don't have a lot of experience with maintaining python projects, so whatever works. I did define an initial .pylintrc to prevent VSCode from complaining about "line too long" when a line fits perfectly on most modern screens, I prefer to be lenient about line length, but it's good to have some tools that can catch situations of possible errors. Open to suggestions.

[JohnRDOrazio]

I see that black is very opinionated:

If Black thinks dicts or JSON-like literals will fit on one line under your line-length, it will collapse it to a single line.

And there is no way to customize that. I think it's prettier to see multiline JSON-like literals, but if we want to choose tools that will allow for consistency I can live with blacks opinions.

[JohnRDOrazio]

And I just fixed the format_calendar_summary method too. After rebuilding the docker image and restarting Claude:

The method does in fact limit the number of results, so Claude just shows some general information. But I think we have a good starting point!
This fix has enabled pretty much all of the tools that are available:

[RandyDanielson]

Finally got the container built and Claude Desktop setup with the litcal MCP server running locally. Took a little longer than expected to setup, mainly because all of my MCP files were completely empty, so had to spend some time figuring out how the YAML files needed to be structured. I'm sure I missed a step somewhere that auto populated them.
Works good though! Will do more testing and experimenting later in the week.

[JohnRDOrazio]

I had installed an example MCP server Obsidian in Docker MCP Toolkit on Docker Desktop, I installed Obsidian desktop and the Obsidian API community plugin, but I haven't yet succeeded in getting the Obisidian MCP server to work. But perhaps that step of installing the example tool got everything setup and into place.