Add "Built with" attribution page
ELI5-style credits page honoring every open source project in the stack: NOAA, MCP, FastMCP, Python, Pydantic, httpx, Matplotlib, Plotly, Astro, Starlight, Lucide, Docker, Caddy, uv, Ruff, pytest, Git. Organized by role (data source, server, charts, docs, infra, dev tools) with conversational descriptions.
This commit is contained in:
parent
f58be224fe
commit
7e76a51f25
199
docs/src/content/docs/understanding/built-with.mdx
Normal file
199
docs/src/content/docs/understanding/built-with.mdx
Normal file
@ -0,0 +1,199 @@
|
|||||||
|
---
|
||||||
|
title: Built with
|
||||||
|
description: The open source projects that make mcnoaa-tides possible
|
||||||
|
sidebar:
|
||||||
|
order: 10
|
||||||
|
---
|
||||||
|
|
||||||
|
import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
|
||||||
|
|
||||||
|
Every piece of mcnoaa-tides stands on the shoulders of open source projects
|
||||||
|
built by people who decided to share their work. This page is a thank-you to
|
||||||
|
all of them.
|
||||||
|
|
||||||
|
## Where the data comes from
|
||||||
|
|
||||||
|
<Card title="NOAA CO-OPS" icon="star">
|
||||||
|
The **National Oceanic and Atmospheric Administration** runs the
|
||||||
|
[Center for Operational Oceanographic Products and Services](https://tidesandcurrents.noaa.gov/) —
|
||||||
|
about 300 tide stations along every U.S. coast, measuring water levels every
|
||||||
|
six minutes. Wind, pressure, temperature too. All of it published as free,
|
||||||
|
public data through a [REST API](https://tidesandcurrents.noaa.gov/api/).
|
||||||
|
|
||||||
|
Without NOAA, there's no mcnoaa-tides. Full stop.
|
||||||
|
</Card>
|
||||||
|
|
||||||
|
## How the server works
|
||||||
|
|
||||||
|
These are the projects that make the MCP server run — the Python code that
|
||||||
|
talks to NOAA's API and translates it into something your assistant can use.
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<Card title="Model Context Protocol" icon="open-book">
|
||||||
|
**[MCP](https://modelcontextprotocol.io/)** is the open standard that
|
||||||
|
lets assistants use tools, read resources, and follow prompts from
|
||||||
|
external servers. Think of it as a USB port for assistants — plug in a
|
||||||
|
server, and the assistant gains new capabilities.
|
||||||
|
|
||||||
|
mcnoaa-tides is an MCP server. That's how your assistant knows how to
|
||||||
|
find tide stations, pull predictions, and generate charts.
|
||||||
|
</Card>
|
||||||
|
<Card title="FastMCP" icon="rocket">
|
||||||
|
**[FastMCP](https://gofastmcp.com/)** is the Python framework that makes
|
||||||
|
building MCP servers feel like writing a regular Python app. Define a
|
||||||
|
function, add type hints, and FastMCP handles the JSON-RPC transport,
|
||||||
|
parameter validation, and error handling.
|
||||||
|
|
||||||
|
It's the reason mcnoaa-tides can declare 14 tools, 4 prompts, and 3
|
||||||
|
resources in clean, readable code.
|
||||||
|
</Card>
|
||||||
|
<Card title="Python" icon="seti:python">
|
||||||
|
**[Python](https://www.python.org/)** — the language everything is
|
||||||
|
written in. Specifically Python 3.12+, which brought nicer type syntax
|
||||||
|
and faster startup times.
|
||||||
|
</Card>
|
||||||
|
<Card title="Pydantic" icon="approve-check-circle">
|
||||||
|
**[Pydantic](https://docs.pydantic.dev/)** validates data using Python
|
||||||
|
type annotations. Every station record, tide prediction, and weather
|
||||||
|
observation passes through a Pydantic model before it reaches your
|
||||||
|
assistant. If the data is wrong, you find out immediately — not three
|
||||||
|
tool calls later.
|
||||||
|
</Card>
|
||||||
|
<Card title="httpx" icon="external">
|
||||||
|
**[httpx](https://www.python-httpx.org/)** is an async HTTP client for
|
||||||
|
Python. It's what actually makes the network requests to NOAA's API
|
||||||
|
endpoints — fetching tide predictions, water levels, and meteorological
|
||||||
|
data. Fast, well-tested, and supports connection pooling out of the box.
|
||||||
|
</Card>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
## How the charts get drawn
|
||||||
|
|
||||||
|
When you ask for a tide chart or conditions dashboard, one of these two
|
||||||
|
libraries does the rendering. They're optional — the server works fine
|
||||||
|
without them, but the visuals are worth installing.
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<Card title="Matplotlib" icon="seti:image">
|
||||||
|
**[Matplotlib](https://matplotlib.org/)** renders the PNG charts — the
|
||||||
|
ones that show up inline in your conversation. It draws the tide curves,
|
||||||
|
marks the highs and lows, overlays observed water levels. The classic
|
||||||
|
scientific plotting library, used everywhere from research papers to
|
||||||
|
satellite missions.
|
||||||
|
</Card>
|
||||||
|
<Card title="Plotly" icon="setting">
|
||||||
|
**[Plotly](https://plotly.com/python/)** generates interactive HTML
|
||||||
|
charts — the ones you can pan, zoom, and hover over for exact values.
|
||||||
|
Saves as a standalone `.html` file you can open in any browser. Great
|
||||||
|
for detailed analysis or sharing with someone who isn't in a chat
|
||||||
|
window.
|
||||||
|
</Card>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
## How the docs site is built
|
||||||
|
|
||||||
|
You're reading this on a site built with these tools. The same
|
||||||
|
maritime-teal theme, the animated wave hero, the conversation-style
|
||||||
|
guides — it's all thanks to this stack.
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<Card title="Astro" icon="astro">
|
||||||
|
**[Astro](https://astro.build/)** is the web framework that builds this
|
||||||
|
entire documentation site. It ships zero JavaScript by default — pages
|
||||||
|
are static HTML until you need interactivity. Fast to load, fast to
|
||||||
|
build, and designed for content-heavy sites like this one.
|
||||||
|
</Card>
|
||||||
|
<Card title="Starlight" icon="starlight">
|
||||||
|
**[Starlight](https://starlight.astro.build/)** is Astro's documentation
|
||||||
|
theme. Sidebar navigation, search, dark/light mode, responsive layout,
|
||||||
|
component library — Starlight provides all of it. The
|
||||||
|
[Diátaxis](https://diataxis.fr/) structure you see (Getting Started,
|
||||||
|
How-To, Reference, Understanding) comes from Starlight's conventions.
|
||||||
|
</Card>
|
||||||
|
<Card title="Lucide" icon="heart">
|
||||||
|
**[Lucide](https://lucide.dev/)** is the open-source icon library used
|
||||||
|
throughout the site. Every little icon you see in cards, navigation, and
|
||||||
|
badges is a Lucide SVG — lightweight, consistent, and beautifully drawn.
|
||||||
|
Community-maintained fork of Feather Icons with 1,500+ icons.
|
||||||
|
</Card>
|
||||||
|
<Card title="Inter & JetBrains Mono" icon="document">
|
||||||
|
**[Inter](https://rsms.me/inter/)** is the sans-serif typeface for body
|
||||||
|
text — designed for screens, optimized for readability at small sizes.
|
||||||
|
**[JetBrains Mono](https://www.jetbrains.com/lp/mono/)** is the
|
||||||
|
monospace font for code blocks — ligatures, clear symbol distinction,
|
||||||
|
and easy on the eyes during long reading sessions. Both served locally
|
||||||
|
via [Fontsource](https://fontsource.org/).
|
||||||
|
</Card>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
## How it gets to you
|
||||||
|
|
||||||
|
The infrastructure that builds, packages, and serves everything.
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<Card title="Docker" icon="laptop">
|
||||||
|
**[Docker](https://www.docker.com/)** packages the server and docs site
|
||||||
|
into containers — self-contained environments that run the same way
|
||||||
|
everywhere. The production docs site is a multi-stage build: Node.js
|
||||||
|
compiles the static HTML, then Caddy serves it. No Node.js in
|
||||||
|
production, just a tiny Alpine-based web server.
|
||||||
|
</Card>
|
||||||
|
<Card title="Caddy" icon="external">
|
||||||
|
**[Caddy](https://caddyserver.com/)** is the web server that serves this
|
||||||
|
site. It handles HTTPS automatically — gets certificates from Let's
|
||||||
|
Encrypt, renews them, and redirects HTTP to HTTPS. Zero configuration
|
||||||
|
for TLS. The production Caddyfile is 9 lines long.
|
||||||
|
</Card>
|
||||||
|
<Card title="uv" icon="rocket">
|
||||||
|
**[uv](https://github.com/astral-sh/uv)** is a fast Python package
|
||||||
|
manager from [Astral](https://astral.sh/). It installs dependencies,
|
||||||
|
resolves versions, and runs scripts — like pip but dramatically faster.
|
||||||
|
The `uvx mcnoaa-tides` command that launches the server without a
|
||||||
|
permanent install? That's uv.
|
||||||
|
</Card>
|
||||||
|
<Card title="PyPI" icon="seti:python">
|
||||||
|
**[PyPI](https://pypi.org/project/mcnoaa-tides/)** — the Python Package
|
||||||
|
Index — is where mcnoaa-tides gets published. When you run
|
||||||
|
`uvx mcnoaa-tides` or `pip install mcnoaa-tides`, PyPI is the registry
|
||||||
|
that serves the package.
|
||||||
|
</Card>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
## The dev tools
|
||||||
|
|
||||||
|
Not visible in the final product, but essential for keeping the code clean
|
||||||
|
and the tests passing.
|
||||||
|
|
||||||
|
<CardGrid>
|
||||||
|
<Card title="Ruff" icon="warning">
|
||||||
|
**[Ruff](https://github.com/astral-sh/ruff)** is an extremely fast
|
||||||
|
Python linter and formatter — also from Astral. It replaces flake8,
|
||||||
|
isort, black, and a dozen other tools with one binary that runs in
|
||||||
|
milliseconds. Keeps the codebase consistent without slowing anyone down.
|
||||||
|
</Card>
|
||||||
|
<Card title="pytest" icon="approve-check-circle">
|
||||||
|
**[pytest](https://pytest.org/)** runs the test suite. Combined with
|
||||||
|
**[pytest-asyncio](https://github.com/pytest-dev/pytest-asyncio)** for
|
||||||
|
testing the async MCP tools, it validates that station discovery works,
|
||||||
|
tide predictions parse correctly, and the visualization pipeline doesn't
|
||||||
|
break.
|
||||||
|
</Card>
|
||||||
|
<Card title="Git" icon="seti:git">
|
||||||
|
**[Git](https://git-scm.com/)** — version control. Hosted on a
|
||||||
|
[Gitea](https://about.gitea.com/) instance. Every change tracked, every
|
||||||
|
deployment traceable.
|
||||||
|
</Card>
|
||||||
|
</CardGrid>
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Thank you
|
||||||
|
|
||||||
|
Open source isn't just code. It's people choosing to share solutions instead
|
||||||
|
of hoarding them. Every project listed here represents thousands of hours of
|
||||||
|
work by people who decided the world would be better if others could build
|
||||||
|
on what they made.
|
||||||
|
|
||||||
|
If you use mcnoaa-tides and find it useful, consider contributing back to
|
||||||
|
any of these projects — even a bug report, a documentation fix, or a thank-you
|
||||||
|
in their issue tracker goes a long way.
|
||||||
Loading…
x
Reference in New Issue
Block a user