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