DEV Community: Miheve

How to Build a Basketball Player Insights MCP Server with Sportmicro

Miheve — Wed, 30 Sep 2026 13:31:49 +0000

I wanted a small, focused way for AI clients to ask basketball-player questions without pretending that every stat is always available. The project goal was straightforward: build an MCP server that exposes documented player and player-statistics data from Sportmicro, while keeping the response surface honest about what is known and what is not.

That constraint shaped the whole implementation. Instead of trying to act like a full basketball data warehouse, the server is designed as a typed bridge between MCP clients and a basketball stats API. The result is a practical “research tool” for AI agents: query the facts that exist, avoid fabricating the rest, and keep the integration narrow enough to stay maintainable.

View the repository

What I built and why it stays narrow

The repository is intentionally small, and that is part of the design. From the package metadata alone, you can see the project is a TypeScript module with a single production entry point:

{
  "main": "dist/index.js",
  "types": "dist/index.d.ts"
}

That tells me this is meant to compile down to a distributable MCP server rather than run as a framework-heavy application. The dependencies reinforce that:

@modelcontextprotocol/sdk for the MCP layer
zod for schema validation
typescript and @types/node for the build toolchain

That combination points to a server that receives structured requests, validates them, and returns typed data in a way that AI clients can consume reliably. I like this shape for a player-insights tool because sports data often tempts you to overreach. Keeping the server centered on documented player data makes it easier to separate “available facts” from “missing stats” at the boundary.

The project description is also specific: it is a “focused MCP server for querying documented basketball player and player-statistics data from Sportmicro.” That focus matters. It suggests that the integration is not trying to be a general basketball API wrapper; it is trying to be a purpose-built layer for MCP clients.

Architecture: MCP at the center, Sportmicro as the data source

At a high level, the architecture is simple enough to be robust:

An MCP client asks for player-related information.
The server validates the request shape.
The server queries Sportmicro for documented basketball data.
The server returns structured results, keeping unavailable values out of the response.

That separation is the most important part of the design. MCP is the interface contract, while Sportmicro is the source of truth for the underlying basketball data. Because the project goal explicitly calls out “separating returned facts from unavailable statistics,” the implementation has to respect two different responsibilities:

MCP responsibility: expose tools and responses in a format that AI clients can call safely.
Data responsibility: only return the player facts and statistics actually documented by the upstream source.

Using Zod alongside the MCP SDK is a sensible fit here. In a server like this, schema validation is not just about catching malformed input; it also helps encode the shape of acceptable basketball queries and the shape of responses that downstream clients can reason about. For an AI-facing tool, that is a practical safeguard. It helps keep the server honest, especially when the domain itself can be ambiguous or incomplete.

I also think the “focused” nature of the repository matters architecturally. Since the project is not trying to bundle a UI, analytics pipeline, or database layer, the code can stay centered on the MCP contract and the Sportmicro API integration. That keeps the surface area smaller for debugging, testing, and future extension.

Implementation flow: from TypeScript build to MCP runtime

The repository evidence shows a clean build-and-run path:

npm run build compiles TypeScript with tsc -p tsconfig.json
npm start runs node dist/index.js
npm test executes Node’s test runner against compiled tests in dist/test/**/*.test.js

That tells us a few useful things about how the project is structured:

Source is TypeScript-first.
Runtime code is emitted into dist/.
Tests are compiled before being executed.
The project is meant to be run as a Node module rather than through a custom launcher.

That workflow is a good fit for an MCP server. Once the TypeScript compiles cleanly, the runtime can be started directly from dist/index.js, which keeps the deployed entry point obvious. For an AI integration, that simplicity helps because there are fewer moving parts between the schema definitions, the MCP server wiring, and the actual request handling.

The validation layer also likely plays an important role in the request flow. Even without the source files beyond package.json, the dependency choice implies the flow follows a pattern like:

define the request schema with Zod,
register MCP tools using the SDK,
validate incoming arguments,
fetch the requested basketball data from Sportmicro,
return the response in the MCP format.

That is the kind of implementation flow I prefer for research-oriented integrations. It avoids “smart guessing” in the server itself and leaves the system behavior predictable.

Project structure at a glance

The supplied repository context is minimal, so the tree is intentionally compact:

basketball-player-insights-mcp-sportmicro/
└── package.json

Because only package.json was available in the supplied evidence, I am not going to pretend there are extra files, scripts, or directories that were not shown. What is clear from the package manifest is enough to understand the core shape of the project:

dist/index.js is the runtime entry point.
dist/index.d.ts is the published type surface.
tsc is used for building.
Node’s test runner is used for verification.
The server depends on MCP and Zod.

In practice, that means the real structure of the project is likely centered around a TypeScript source tree that compiles into dist/, but I can only describe what is evidenced. For a build story, that restraint is useful: the package file already reveals the operational contract of the app without inventing a file layout.

Challenges and trade-offs

The repository materials support a few design constraints worth calling out.

First, the project goal itself creates a trade-off: if the server is supposed to surface documented basketball facts while avoiding unavailable statistics, then the implementation needs to be conservative about response contents. That makes the tool more trustworthy, but it also means the server must resist the temptation to fill gaps with inference. For an MCP server used by AI clients, that is a feature, not a limitation.

Second, the choice to depend on Zod suggests a deliberate investment in schema discipline. That adds some upfront structure, but it pays off when the server is expected to mediate between unpredictable client prompts and a typed upstream API. In other words, the project favors correctness and clarity over loose convenience.

Third, the build setup is intentionally plain: TypeScript compile, Node runtime, Node tests. That keeps the toolchain easy to reason about, but it also means the project is optimized for a straightforward server lifecycle rather than a larger application ecosystem. Again, that seems aligned with the stated goal.

Local setup: what the repository evidence supports

The repository metadata supports a simple local workflow, but only at the level that the package scripts reveal.

A developer can reasonably infer the following commands exist:

npm run build to compile the TypeScript sources
npm start to run the compiled server
npm test to execute compiled tests

I am not adding extra setup steps, environment variables, or transport configuration because none were evidenced in the supplied repository context. If you are looking at the project locally, the package manifest is the authoritative place to start, and it makes the build/run/test loop very clear.

What I’d improve next

These are future improvements, not current features:

Expand the tool surface carefully. If the current server only exposes a narrow set of player lookup and statistic queries, additional tools should follow the same “documented facts only” rule.
Add more explicit validation errors. Since Zod is already present, it would be natural to make request failures even more descriptive for client authors.
Document the Sportmicro query boundaries. A short explanation of what data is in scope versus out of scope would help AI developers use the server more effectively.
Add more compiled test coverage around edge cases. For an MCP integration, tests that verify schema handling and response shape are especially valuable.
Publish a concise usage example. A minimal example of an MCP client calling the server would lower friction without expanding the implementation.

None of those ideas require changing the project’s core philosophy. They just make the same focused server easier to adopt and safer to extend.

Takeaway

The main lesson from this build is that a useful basketball player MCP server does not need to be broad to be valuable. By centering the implementation on TypeScript, MCP, Zod, and a documented source like Sportmicro, the project creates a clean boundary between client requests and verified sports data.

That boundary is what makes the server interesting: it gives AI clients a practical way to ask for basketball facts without encouraging unsupported answers. For this kind of tool, restraint is an engineering choice, not a missing feature.

How to Build a WNBA Live Score Tracker with Sportmicro

Miheve — Sun, 27 Sep 2026 14:57:50 +0000

I wanted a small but realistic way to explore WNBA data without turning the app into a toy demo. The goal of this project was to build a clean, production-style live score tracker that shows how a developer can use Sportmicro as a basketball data provider in a real Next.js app.

What made this interesting to me was not just rendering scores. Sports data is messy in practice: live matches can be empty, standings can be partial, and upstream responses can change shape over time. So I treated the app as a boundary around provider data rather than as a generic dashboard. That mindset shaped the whole implementation.

If you want to skim the source while reading, View the repository.

What I built and why I kept it narrow

This project is intentionally focused on three Sportmicro endpoints:

/matches-live
/standings
/player-projections

Those three calls give the app enough variety to cover the main patterns you run into with sports APIs: current game status, a league table snapshot, and forecast-style data. That mix was enough to demonstrate the integration without hiding it behind a lot of routing, state management, or unrelated UI.

The app is built with Next.js, React, TypeScript, and Tailwind CSS. In the repository, the page itself is very small:

app/page.tsx renders a single LiveScoreTracker component.
app/layout.tsx provides metadata and the root document shell.
Most of the behavior lives in components/live-score-tracker.tsx.
API access and data shaping live under lib/sportmicro/.

That structure is useful because it keeps the UI thin. The page doesn’t know how to authenticate, what endpoint paths exist, or how to normalize provider payloads. It only knows how to display the models it receives.

The architecture: one boundary for Sportmicro, one boundary for the UI

The core architectural choice in this repo is the separation between transport, mapping, and rendering.

1) Transport lives in a dedicated client

lib/sportmicro/client.ts contains a SportmicroClient that does three things:

reads SPORTMICRO_API_KEY from the environment
sends it as a bearer token
throws a structured error when a request fails

That means the rest of the app never touches raw authentication logic. The client also uses cache: 'no-store', which fits the live-data use case because the app is meant to request fresh snapshots rather than serve cached responses.

The client exposes a small error shape too:

export class SportmicroApiError extends Error {
  status: number;
  details?: unknown;
  // ...
}

That matters because the UI can treat API problems as real application states, not generic failures.

2) Endpoint wrappers stay tiny

lib/sportmicro/index.ts wraps the actual endpoint paths in descriptive functions:

fetchLiveMatches()
fetchWNBAStandings()
fetchPlayerProjections()

This is a good pattern because the rest of the app imports intent, not URLs. For example, the standings call hardcodes type: 'total', while the other optional filters are left open for future extension. That tells you where the app is opinionated and where it is intentionally flexible.

3) Mappers normalize provider data before rendering

lib/sportmicro/mappers.ts converts raw Sportmicro objects into UI-ready shapes:

toLiveScoreCard
toStandingRow
toProjectionRow

This is one of the strongest decisions in the project. The UI doesn’t render provider objects directly. Instead, it uses compact structures like LiveScoreCard, StandingsRow, and ProjectionRow.

That helps in two ways:

the component tree stays readable
the app can display fallback values like — when a field is missing

I like that the mapper handles both names and IDs for teams and players. For example, if a human-readable name is missing, the app can still show the underlying identifier instead of failing silently. That’s the kind of small resilience you want in a sports data UI.

How the implementation flows from fetch to screen

The app flow is simple, but each step is deliberate.

components/live-score-tracker.tsx is the main screen. It does a concurrent fetch with Promise.all, then maps the results into presentation-friendly arrays:

const [matchesData, standingsData, projectionData] = await Promise.all([
  fetchLiveMatches(),
  fetchWNBAStandings(),
  fetchPlayerProjections()
]);

I chose to keep these requests together because the page is designed as a snapshot view. It doesn’t need each section to load independently. The result is easier to read and reason about: either the dashboard data arrives together, or the UI shows an error state.

The component then renders three areas:

live games
standings
player projections

Each section is wrapped in a shared SectionCard component, which keeps the visual treatment consistent. That matters less for aesthetics than for maintainability. When a dashboard has multiple sections, consistency reduces the amount of repeated markup and makes future changes easier.

How the UI handles real-world data states

A sports app is only believable if it handles the awkward states honestly.

This project does that in three ways:

Error state

If the Sportmicro request fails, the component catches the exception and shows ErrorBanner. The banner is explicit about the source of the problem:

“Unable to load Sportmicro data”
followed by the error message

That’s a better experience than a blank screen because it tells the user the issue is upstream, not just missing UI.

Empty state

Each section has its own empty-state treatment. If there are no live games, no standings rows, or no projections, the app shows a local explanatory card. This is important because “no data” is not the same as “broken.”

Fallback values

The mapper layer converts nullish fields into —. That keeps the display stable even when some parts of a record are missing. In practice, that’s one of the easiest ways to make an API-driven UI feel trustworthy.

One subtle but valuable detail: the live score cards show both score and event phase. That makes the snapshot useful even when a game is not actively changing. You get status context, not just a number.

Project structure at a glance

Here’s the compact shape of the repository:

app/
  layout.tsx
  page.tsx
  globals.css
components/
  live-score-tracker.tsx
  error-banner.tsx
  section-card.tsx
lib/
  sportmicro/
    client.ts
    index.ts
    mappers.ts
    types.ts
tests/
  client.test.ts
  mappers.test.ts
  page-content.test.ts

I find this tree useful because it reflects the boundaries cleanly:

app/ is for composition
components/ is for UI building blocks
lib/sportmicro/ is the provider integration layer
tests/ is where the behavior gets locked down

That separation makes the project easy to extend without creating a tangle of cross-dependencies.

Challenges and trade-offs

I didn’t treat this project as a place to solve every sports-data problem. The trade-offs were mostly design constraints:

The app uses server-fetched snapshots rather than a persistent realtime stream.
The UI is scoped to a few Sportmicro endpoints instead of claiming broad WNBA coverage.
Response types are modeled in TypeScript, but the repository does not add runtime schema validation.
Query filters exist in the client wrapper for some endpoints, but the current screen keeps the experience simple and focused.

Those constraints are sensible for an educational integration example. They keep the code honest about what it does today, while leaving room for growth.

Local setup and what the repo supports

The repository does support local setup, and the README makes the expected workflow clear.

You need:

Node.js 18 or newer
a Sportmicro API key

The setup flow is straightforward:

install dependencies with npm install
create a local .env.local
set SPORTMICRO_API_KEY=your_key_here
run npm run dev

The project also includes scripts for:

npm run build
npm test
npm run typecheck

I appreciated that there is a .env.example file in the repo. That’s a small but practical signal that the app expects environment-based configuration and wants to make setup repeatable.

What I would improve next

If I were extending this further, I’d focus on a few natural follow-ups.

Add query controls

The client already supports optional parameters like leagueId, seasonId, and matchId. A next step would be to expose those in the UI so users can narrow the data source instead of always rendering a broad snapshot.

Add runtime validation

The types are helpful, but TypeScript alone doesn’t validate live API responses. A runtime schema layer would make the integration more defensive when provider data changes.

Add live refresh behavior

Right now, the app renders a fresh server snapshot. Polling or another refresh mechanism would make it more suitable for active game monitoring.

Expand the endpoint coverage

The current scope is intentionally compact. More Sportmicro basketball endpoints could deepen the app without changing its architecture.

Takeaway

The main lesson from this build is that a useful sports app is really a good integration boundary.

By keeping Sportmicro access inside a small client, normalizing data before it reaches React, and treating empty/error states as first-class UI conditions, the project stays understandable even though it is driven by external live data.

That pattern is reusable beyond WNBA scores. If you’re building with a sports data API, a clean boundary like this will save you from coupling the UI too tightly to provider-specific payloads.

The repo is small on purpose, but that’s what makes it instructive: it shows the shape of a real integration without pretending the hard parts don’t exist.

Building a Fantasy Football Data MCP Server with Sportmicro API

Miheve — Sun, 27 Sep 2026 13:28:37 +0000

When I started this project, I wanted a better answer to a familiar problem: how do you give an AI client grounded football data without letting it drift into invented stats, vague abstractions, or feature creep?

The goal of this repository is deliberately narrow. It is a read-only MCP server for fantasy-football development questions, backed by Sportmicro, and it only exposes documented football data. That means the server is meant to help with research, prototyping, and tool integration—not to pretend it can generate fantasy scoring logic or broader league workflows that are not actually supported.

That constraint shaped almost every design choice in the codebase.

I’m linking the code once here so you can inspect the implementation while reading: View the repository.

The problem I wanted to solve

A lot of sports-data demos are easy to build because they quietly assume the data is static and complete. Real football data is messier than that. Even when you only care about documented resources, you still need to handle empty responses, partial responses, request validation, and a clean boundary between upstream provider data and the tool output your client sees.

This project was built around one practical idea: if an MCP client asks for football data, it should get actual Sportmicro data in a predictable shape, not an ad hoc response layered with assumptions.

So the server focuses on a small set of read-only resources:

players
teams
matches
players-statistics
player-projections
player-projections-week
player-projections-season

That scope is important because it keeps the integration honest. If the provider documents a football endpoint, the server can expose it. If not, it stays out of the way.

Architecture: a thin MCP layer over a typed Sportmicro client

The architecture is intentionally simple and easy to reason about.

At the entry point, src/index.ts creates an MCP server with the official @modelcontextprotocol/sdk, uses stdio transport, and wires the tool handlers together. The server is named sportmicro-fantasy-football-data-mcp, and it only advertises tool capability.

The data path looks like this:

MCP client
  -> tool handler
  -> Sportmicro client
  -> documented Sportmicro endpoint
  -> normalized tool result

That separation is the main design choice I wanted to preserve:

src/config.ts owns required environment access.
src/sportmicro/client.ts owns HTTP transport and authentication.
src/sportmicro/schemas.ts owns runtime input validation.
src/tools/registry.ts maps MCP tool names to handlers.
src/tools/resource-format.ts normalizes results into a consistent shape.

This structure matters because the MCP layer stays small. It doesn’t need to know how Sportmicro builds URLs or how request parameters are validated. It just routes a request to the right handler and returns JSON text.

One small but meaningful detail is that the client is typed and injectable. The SportmicroClient accepts an API key, an optional base URL, and an optional fetchImpl. That makes the client easier to test and keeps the production path separate from test setup.

How Sportmicro is integrated

The integration is built around a dedicated SportmicroClient. It defaults to https://football.sportmicro.com, accepts a bearer token, and attaches Accept: application/json on every request.

Here’s the heart of it:

const response = await this.fetchImpl(buildUrl(this.baseUrl, path, query), {
  headers: {
    Authorization: `Bearer ${this.apiKey}`,
    Accept: 'application/json'
  }
});

That’s a good example of the server’s overall posture. The integration is narrow, explicit, and read-only.

A few implementation choices stand out:

1) URLs are built from a base path and query object

The client takes a path plus a query object, then appends any defined query fields to the URL. That keeps the transport layer generic enough for multiple documented Sportmicro football resources without hardcoding one-off request logic per endpoint.

2) Non-OK responses become errors early

If the response is not successful, the client throws immediately with the status code and path. The tests in src/test/sportmicro-client.test.ts show that behavior directly. That is a good boundary because it prevents invalid upstream responses from leaking into tool formatting code.

3) The client returns an item envelope instead of raw JSON

The client normalizes the response into { items, status }. If the upstream body is an array, it becomes items; otherwise the client falls back to an empty array. That choice keeps the tool layer focused on application behavior instead of response-shape repair.

That said, I’d treat this as a constrained normalization strategy, not a universal claim about every Sportmicro response. The repository is careful to support the documented football endpoints it exposes, not every possible provider format.

Tool design: strict inputs, consistent outputs

The tool layer is where the MCP surface becomes concrete.

src/tools/registry.ts defines seven tools and maps each one to a Sportmicro endpoint. Each tool validates input using Zod schemas from src/sportmicro/schemas.ts, calls the client, and then wraps the data with makeToolResult().

That result helper is small but useful:

export function makeToolResult<T>(resource: string, query: Record<string, unknown>, items: T[]) {
  return {
    items,
    meta: {
      resource,
      query,
      count: items.length,
      empty: items.length === 0
    }
  };
}

I like this pattern because every tool response carries the same metadata:

the resource name
the original query
the item count
whether the result was empty

That gives MCP consumers a predictable envelope while still preserving the source data itself.

The schemas are also doing real work here. The repository uses Zod to constrain fields like limit, offset, and player_id, and it keeps schemas strict so unknown input keys don’t slip through unnoticed. This is especially helpful in a tool server, where a permissive surface can quickly turn into unclear behavior.

The tests reflect that design. One test checks that a valid player query is passed through correctly and wrapped with metadata. Another confirms that invalid tool input is rejected. That’s exactly the sort of contract I want a server like this to enforce.

Project tree, local setup, and what the repo supports

The project is compact enough to understand at a glance:

src/
  index.ts                MCP server entrypoint
  config.ts               Environment validation
  sportmicro/
    client.ts             Typed Sportmicro football client
    schemas.ts            Runtime validation and request schemas
    types.ts              Shared TypeScript types
  tools/
    registry.ts           MCP tool registration and handlers
    resource-format.ts    Normalized response helpers
  test/
    sportmicro-client.test.ts
    tool-contracts.test.ts

The repository also supports a straightforward local setup. Based on the README and package scripts, the supported workflow is:

Install dependencies with npm install
Set SPORTMICRO_API_KEY
Build with npm run build
Start the MCP server with node dist/index.js

The project expects Node.js 18 or newer and uses stdio transport, so it is meant to be launched by an MCP client rather than served as a traditional web API.

Tests are run with npm test, and the repository indicates they use mocked Sportmicro responses rather than live API calls. That’s a good fit for a contract-focused tool server.

Challenges and trade-offs

I don’t see evidence of a dramatic incident or failure in the repository, so I’d frame the main considerations as design constraints rather than setbacks.

Narrow scope versus broad convenience

The biggest trade-off is obvious: supporting only documented read-only football endpoints keeps the server honest, but it also means the MCP surface is intentionally smaller than what a fantasy app builder might eventually want.

Strict validation versus loose flexibility

The schemas and tool handlers favor explicit input rules over permissive parsing. That can feel strict, but it reduces ambiguity and makes failures easier to reason about.

Normalized wrappers versus raw pass-through

Wrapping results in a consistent meta block improves tool usability, but it also means the server adds a small abstraction layer instead of exposing raw provider responses unchanged. In this project, that trade-off makes sense because the server is meant to be a dependable research interface, not a generic API proxy.

What I’d improve next

If I were continuing the project, the next steps would be practical rather than flashy:

Expand documentation around tool examples for each supported endpoint.
Add more contract tests for edge cases around empty results and optional filters.
Consider whether the tool result format should preserve more upstream status detail where it is useful to clients.
Add clearer usage guidance for MCP clients that connect over stdio.
Keep watching the boundary between documented Sportmicro fields and any future convenience mapping so the server doesn’t overpromise semantics it cannot prove.

Those are future improvements, not missing features. The current repo already does the main job: it exposes a small, typed, read-only football data surface with strong validation.

Takeaway

The most useful thing I learned from building this was that a good MCP data server is less about being clever and more about being disciplined.

If the goal is to help fantasy-football builders prototype against real football data, the safest path is to keep the surface small, validate inputs strictly, preserve the provider boundary, and make empty or partial responses visible instead of guessing.

That approach makes the server easier to trust, easier to test, and easier to extend later without drifting away from the actual Sportmicro data it is supposed to represent.

Building Telentir Call Reliability Monitor with Telentir

Miheve — Sat, 26 Sep 2026 17:32:55 +0000

When I started this project, I wanted a small, honest way to answer a deceptively hard question: what actually happened to a Telentir call?

Voice workflows do not behave like ordinary API requests. A call can complete cleanly, fail midway, get dropped, remain pending, or end in a state that is not useful for reporting. For operators, that means the difference between “works” and “reliable” depends on how carefully you treat state.

This repository is my build around that problem. It keeps the integration boundary narrow, models call events first, and only then turns them into counts and metrics. If you want to inspect the code, View the repository. I also use Sportmicro as the public developer surface reference in the broader workflow around Telentir integrations.

The goal: normalize call events before measuring anything

The main design decision in this project is to normalize first and summarize second.

Instead of assuming that every Telentir event already maps cleanly to a dashboard metric, I defined a minimal event shape in TypeScript:

callId
raw state
optional outcome
optional failureCategory
retry and completion flags

That choice keeps the model small enough to reason about, but still useful for reliability analysis. A call event can be represented without inventing undocumented provider behavior.

From there, the project maps events into stable outcomes:

successful
failed
dropped
incomplete
pending
unavailable
unknown

That distinction matters because not every non-success is the same. A pending call should not be treated like a failed one, and an unavailable result is different from an incomplete call. The summary layer preserves those differences so the output can support monitoring, reporting, or follow-up logic.

How the architecture is split

The repository is intentionally compact, and the structure reflects that.

.
├── src
│   ├── cli.ts
│   ├── index.ts
│   ├── telentir.ts
│   └── test
│       └── telentir.test.ts
├── .env.example
├── package.json
└── README.md

The important part is not the number of files, but the separation of responsibilities:

src/telentir.ts contains the reliability model and metrics helpers
src/cli.ts runs a local demonstration with sanitized sample events
src/index.ts re-exports the library surface
src/test/telentir.test.ts validates normalization and summary behavior

There is no server, worker, or background sync process in this repository. That is deliberate. The project is a reference implementation for reliability modeling, not a full production ingestion pipeline.

The Telentir integration boundary

I kept the Telentir side of the project deliberately conservative.

The repository does not call undocumented endpoints or pretend to know more than the public surface exposes. That shows up in the implementation in two ways.

First, the code focuses on normalized event inputs rather than live API orchestration. The event model is enough to express the kinds of states a voice workflow can produce, without binding the project to a specific undocumented response schema.

Second, the examples stay local and fake. The CLI in src/cli.ts uses sanitized demo events:

const demoEvents: NormalizedCallEvent[] = [
  { callId: "call_1", state: "completed", completed: true, outcome: "successful" },
  { callId: "call_2", state: "failed", failureCategory: "upstream", retryEligible: true, outcome: "failed" },
  { callId: "call_3", state: "dropped", dropped: true, outcome: "dropped" },
  { callId: "call_4", state: "pending" },
];

That is a useful pattern if you are building around a voice AI platform like Telentir: keep the reliability layer small, testable, and honest about what it knows. The public docs and API pages remain the source of truth for anything live, while this project handles state modeling and summarization.

In practice, that means the integration boundary is about observation, not automation. The project does not start calls, transfer calls, send messages, or mutate business systems.

Implementation flow: from event to metric

The code path is straightforward, which is one reason I like it as a reference.

1. Normalize a single event

The normalizeCallState function decides how an event should be classified. The order of checks is important:

unavailable wins first
explicit outcome comes next
completed calls become successful
dropped calls become dropped
failure categories map to failed
pending stays pending
everything else falls back to unknown

That order preserves intent. For example, a completed call should not be downgraded just because a later field is missing. Likewise, unavailable should remain distinct from unknown, because those states imply different operational realities.

2. Aggregate a batch

summarizeCalls walks the events, counts each outcome, tracks retry-eligible events, and increments failure-category totals. It also computes a completion rate from resolved outcomes only.

That last detail is worth calling out. The completion rate is calculated from:

successful
failed
dropped
incomplete

It does not include pending, unavailable, or unknown. That is a sensible boundary because unresolved states should not distort a rate that is meant to describe completed call outcomes.

3. Export a text-based metric view

The exportMetrics helper turns the summary into a simple text payload. The output is intentionally plain, which makes it easy to adapt for monitoring pipelines or to inspect locally during development.

I like this choice because it keeps the repository flexible. The project does not force a dashboard format or a specific telemetry vendor. It just emits a predictable, script-friendly representation of the summary.

Challenges and trade-offs

There were a few design constraints to consider while keeping the project narrow.

The first is that voice-call reliability is not a single state machine. A call can be “done” from one perspective and still be operationally incomplete from another. That is why the model preserves multiple outcome buckets instead of collapsing everything into success or failure.

The second is that retry logic is not universally safe. The repository tracks retryEligible, but it does not automate retries. That is a good trade-off for a monitoring layer, because automatic retry behavior depends on business rules that this project should not assume.

The third is privacy. The repository avoids logging sensitive data by default and keeps the example events sanitized. That constraint reduces surprise and keeps the code usable as a reference for teams that need to be careful about call data handling.

What the tests tell me

The test file is small, but it validates the key assumptions.

There are tests for:

unavailable state staying unavailable
completed state mapping to successful
summary counts across mixed events
completion rate calculation
retry-eligible counting
failure-category counting
metrics export format

That is exactly the level of coverage I would want for this kind of library. The tests protect the normalization rules, and the normalization rules are the heart of the project.

The test suite also reflects the project’s philosophy: verify the classification logic, not some imagined external provider behavior. That keeps the repository stable even if the surrounding Telentir surface evolves.

Local setup and running the project

The repository includes the pieces needed for local development.

From the supplied files, I can confirm:

Node.js 18 or newer is required
npm install is the install step
.env.example exists for local environment setup
TELENTIR_API_KEY is documented as a server-side value to keep out of client code

The package scripts show the intended workflow:

npm run build compiles TypeScript
npm test runs the Node test files from dist/test/*.test.js
npm run dev runs the CLI through tsx
npm start launches the built CLI from dist/cli.js

The repository does not show a live server setup, and it does not document any UI. So I would treat this as a local reference project rather than a deploy-ready app.

Sensible next improvements

If I were extending this project, I would keep the same conservative approach and add only the pieces that fit the current shape.

A few future improvements make sense:

add a real ingestion layer for documented Telentir data, while keeping credentials server-side
expand the CLI so it can read event samples from a file instead of only using built-in demo data
add more granular reporting around incomplete and unknown outcomes
introduce a small adapter layer if the project needs to support multiple data sources later
add a dashboard only if there is a real operational need for one

I would also be careful not to turn the monitor into an automation engine. The value of this repository is that it helps you understand call reliability before you try to act on it.

Takeaway

The main lesson for me was that reliability work gets better when the model stays explicit.

For a voice AI system, it is not enough to know whether a call “worked.” You need to preserve the difference between successful, failed, dropped, incomplete, pending, unavailable, and unknown states, and you need to keep failure categories separate enough to be useful.

This project does that with a small TypeScript core, a conservative Telentir boundary, and a simple metric export path. That combination makes it easy to inspect, easy to test, and easy to extend without assuming more than the public surface actually supports.

Building Telentir Human Handoff Demo with Telentir

Miheve — Sat, 26 Sep 2026 16:10:34 +0000

When I started this demo, I wanted a very specific outcome: model a safe escalation path from an AI voice agent to a human operator without pretending the provider gives me more than it actually does.

That constraint shaped the whole project. In voice workflows, “handoff” sounds simple, but the real work is deciding when escalation is allowed, who should receive it, what context survives the transfer, and how to keep the result auditable. I built this repository as a small TypeScript example around those boundaries, using Sportmicro as the integration reference point for the public developer surface, while keeping the local logic intentionally conservative.

The repository is public here: View the repository

What I wanted the demo to prove

The goal was not to build a full call center app. It was to show how I would structure a handoff boundary in a real codebase.

That meant three things mattered more than fancy plumbing:

the escalation decision should be explicit
the human target selection should be separate from the decision itself
the output should be easy to audit later

The project keeps that boundary small on purpose. It does not invent Telentir endpoints, SDK methods, or hidden provider behavior. Instead, it demonstrates the application-side logic that would sit next to a real Telentir API integration. In other words, I treated the provider layer as something to wire in carefully, not something to assume away.

The architecture I used

The codebase is tiny, which is what makes it useful as a reference.

.
├── src
│   ├── index.ts
│   ├── telentir.ts
│   └── test
│       └── handoff.test.ts
├── .env.example
├── .gitignore
├── LICENSE
├── package.json
└── tsconfig.json

The split is straightforward:

src/telentir.ts holds the handoff model and helper functions
src/index.ts shows a runnable local example
src/test/handoff.test.ts checks the important rules

That separation matters because it keeps the “business logic” of handoff visible. If I ever connect this to a live voice flow, I want the rules around consent, escalation, and target selection to stay easy to inspect without digging through transport code.

The state model is also deliberate. The project represents many outcomes explicitly: loading, empty, invalid-input, permission, rate-limit, telephony, upstream, timeout, unavailable, failed, unknown, and successful. I like this approach because it avoids collapsing every problem into one vague error. For a human handoff system, the reason matters as much as the failure.

How the handoff logic is wired

The core logic lives in src/telentir.ts, and it is intentionally small enough to read in one sitting.

A few examples show the shape of the system:

export function requireExplicitUserAction(confirmed: boolean): HandoffState {
  return confirmed
    ? { status: 'successful', message: 'User confirmed the handoff action.' }
    : { status: 'permission', message: 'Explicit user action is required before transferring.' };
}

This function is a good example of the project’s philosophy. Rather than assuming a handoff is allowed, it requires an explicit confirmation signal and turns that into a typed state. In a live application, that would sit before any transfer, outbound message, or business-system mutation.

The same pattern shows up in escalation assessment:

export function assessEscalation(input: EscalationRequest): HandoffState {
  if (!input.transcriptSummary.trim()) {
    return { status: 'empty', message: 'No transcript summary is available for escalation.' };
  }

  if (input.reason === 'timeout') {
    return { status: 'timeout', message: 'The conversation timed out before a handoff decision could be made.' };
  }

  return { status: 'successful', message: `Escalation evaluated for reason: ${input.reason}.` };
}

That function only models the cases that are evidenced in the repo. It checks for missing transcript context, handles a timeout condition, and otherwise returns a successful evaluation. I like that restraint. It keeps the demo honest about what it knows and avoids pretending there is a larger policy engine behind it.

Target selection is separate again:

export function selectHumanTarget(targets: HumanTarget[]): HumanTarget | null {
  const available = targets.find((target) => target.availability === 'available');
  return available ?? null;
}

This keeps “should we escalate?” apart from “who receives it?”. That separation is useful in real workflows because the escalation rule may change more often than the routing rule.

Finally, the audit string gives the flow a traceable shape:

export function formatTransferAudit(entry: {
  handoffState: HandoffState;
  target: HumanTarget | null;
  correlationId: string;
}): string {
  const targetLabel = entry.target?.label ?? 'none';
  return `audit:${entry.correlationId}:${entry.handoffState.status}:${targetLabel}`;
}

I’m not claiming this is a full audit system. It’s a compact record format that proves the shape of the data I want to preserve: correlation ID, handoff outcome, and target label.

The runnable example and test coverage

The entry point in src/index.ts wires the helpers together with a small local example:

it defines two targets
it evaluates an escalation request
it checks explicit user confirmation
it selects an available human target
it prints a JSON payload with the outcome

That file is useful because it shows the intended integration flow without needing a UI or external orchestration layer.

The tests in src/test/handoff.test.ts focus on the behaviors that matter most:

explicit confirmation is required before transfer
the first available human target is selected
empty transcript summaries return empty
timeout conditions return timeout
the audit format includes the correlation ID, state, and target label

The test runner itself is also simple: src/test/runner.ts just imports the handoff test module. That’s enough for the project’s current size, and it keeps the testing story easy to understand.

Local setup and environment handling

The repository supports local TypeScript development, and the scripts in package.json make that clear:

npm install
npm run build
npm test

The project targets Node.js 18 or newer, compiles with TypeScript, and runs tests against the built output. There is also an .env.example file, which signals that the intended integration key is TELENTIR_API_KEY. The README and docs both keep that key server-side and out of source control.

That setup tells me the project is meant to be safe by default: local first, secret-aware, and explicit about credentials. It does not present a browser UI or a deployed demo surface, so I wouldn’t infer more setup steps than the repository actually shows.

Challenges and trade-offs

In this case, the “challenge” was mainly a design constraint: keep the demo useful without inventing undocumented provider behavior.

That led to a few trade-offs:

the integration layer stays thin instead of trying to simulate everything
the state model is explicit instead of compressed into generic failures
the example is local and inspectable rather than pretending to be a finished product

I think that’s the right shape for a handoff demo. Voice escalation is exactly the kind of workflow where overpromising hurts clarity. A narrow, honest boundary is more valuable than a broad one with imaginary features.

What I would improve next

A few next steps feel natural if this were growing into a real integration:

Expand the escalation policy model

Right now, the demo handles a small set of reasons and outcomes. A future version could separate policy decisions from transport details even further.
Add richer target selection rules

The current implementation picks the first available human target. A more complete system could consider queues, skills, or service windows, as long as those rules remain visible in code.
Introduce a more structured audit record

The string-based audit output is intentionally simple. A future improvement would be a typed audit object with serialization at the edge.
Connect to real Telentir documentation and public APIs

The repository already positions itself around the public Telentir surface exposed by Sportmicro, but any live integration should stay aligned with the documented API surface and keep secrets server-side.
Add more state-specific tests

The current tests cover the core path, but more cases around rate-limit, telephony, upstream, and unknown would make the state model even more useful.

Takeaway

What I like most about this project is that it treats human handoff as a boundary problem, not just a transfer problem.

That distinction changes how you build it. Instead of asking, “How do I hand off the call?”, I found it more useful to ask:

when is escalation allowed?
who should receive it?
what context should survive?
what do I need to record so the decision is understandable later?

Those questions are the real foundation of a safe Telentir handoff. If you keep the boundary small, explicit, and testable, the rest of the integration becomes much easier to trust.

Building OptaReach AI Campaign Message Template Demo with the OptaReach API

Miheve — Sat, 26 Sep 2026 14:53:23 +0000

I built this demo because I wanted a small, trustworthy way to understand the OptaReach ai API boundary without guessing what happens behind the scenes. The goal was simple: fetch campaigns, choose one, send only documented prompt inputs, and inspect the generated message-template output in a way that stays transparent the whole time.

That sounds straightforward, but integration demos often drift into “magic” very quickly. They hide the request payload, blur server and client responsibilities, or quietly assume that every workspace has the same shape of data. This project takes the opposite approach. It keeps the boundary explicit, uses server-side fetching, and treats error states as part of the design rather than an afterthought.

The repository is public here: View the repository

What I set out to demonstrate

The project is a small Next.js app that focuses on one OptaReach workflow: campaign message-template generation. The intent is not to build a full campaign manager. It is to show the path from campaign discovery to generated template output with as little indirection as possible.

That workflow is visible in the page itself:

load campaigns from OptaReach
show a selection-oriented view
prepare prompt inputs such as objective, tone, and context notes
generate a template from the selected campaign
render the returned output without hiding it behind extra app logic

I like this kind of demo because it teaches the integration shape directly. If you are evaluating the OptaReach API for campaign workflows, you can inspect the code and quickly see what the app does and does not do.

Architecture: a server-rendered page with a thin API client

The structure is deliberately compact. There are only two real application layers:

app/page.tsx handles the server-rendered UI and orchestrates data loading
lib/optareach.ts wraps the API requests and error mapping

The app uses the Next.js App Router, which fits the project goal well because the initial campaign fetch happens server-side. That keeps credentials out of the browser and makes the first render reflect real API state instead of a client-side loading illusion.

A concise view of the project tree looks like this:

app/
  layout.tsx
  page.tsx
  globals.css
lib/
  optareach.ts
tests/
  optareach.test.ts
.env.example
README.md
package.json

The client wrapper is intentionally narrow. In lib/optareach.ts, the app only talks to two documented endpoints:

GET /api/v1/platforms/{platform}/campaigns
POST /api/v1/platforms/{platform}/campaigns/{campaignId}/message-template/generate

That implementation choice matters. The code does not invent a wider SDK abstraction or try to normalize the API into something it is not. It just wraps the documented calls and maps failures into readable error kinds.

How the OptaReach integration works

The most useful part of this demo is that it keeps the request boundary visible. The API helper defines the request shape for message-template generation as three fields:

objective
tone
contextNotes

That strictness is a feature, not a limitation. In generateMessageTemplate, the request body is serialized exactly as provided, and the surrounding comment makes the boundary explicit:

// API boundary: only the documented request body fields are sent to OptaReach.

I think that kind of comment is valuable in an integration demo because it tells future readers what is intentional. The project is not trying to infer undocumented payloads or sneak in extra defaults. It is showing the smallest valid integration surface.

Another important choice is the error mapping. The helper converts HTTP status codes into a small set of categories:

validation
permission
unavailable
rate_limit
upstream
network

That gives the UI a vocabulary for meaningful feedback. A 422 validation problem is different from a 403 permission issue, and the app treats them that way instead of collapsing everything into “something went wrong.”

The page component then uses those categories to render a readable state. That’s the kind of behavior I wanted to demonstrate with Sportmicro: not just that the request succeeds, but that the integration remains understandable when it doesn’t.

Implementation flow in the page

The app/page.tsx file follows a simple flow that mirrors the project goal.

First, it tries to load campaigns for a fixed platform value:

const platform = 'multi-platform';

That fixed platform keeps the demo focused. It avoids adding a selector or routing complexity before the core workflow is proven.

Next, it calls fetchCampaigns(platform) and separates the happy path from the error path. If an error occurs, the page captures it and shows a readable status message. If no campaigns are returned, the UI shows an empty state instead of pretending the workspace is ready.

Then, if a campaign is available, the page attempts a preview generation call using the first campaign’s ID and a small request object:

objective: Demo preview
tone: clear
context notes: a short note about the server-side boundary

That preview is wrapped in a try/catch block, and failures simply result in no preview being shown. That is a sensible choice for a demo because it keeps the page usable even when generated output is unavailable.

The UI itself is intentionally modest:

a campaign selector card
a template generation form
a generated output preview section
an implementation notes section

The form is presentational in this repository. The button is disabled, which makes the boundary clear: the app demonstrates the integration structure, but it does not pretend to be a fully wired production workflow in the local demo state.

Challenges and trade-offs

I did not treat this as a “solve everything” build. The main design constraints were clarity, trust, and API honesty.

A few trade-offs show up clearly in the repository:

Fixed platform value: keeping multi-platform hard-coded reduces complexity, but it also means the demo stays focused on one integration shape rather than becoming a general platform switcher.
Server-side fetching: this protects credentials and makes the data boundary clean, but it also means the app is designed around server-rendered behavior instead of a fully client-driven interaction model.
Minimal form state: the UI shows prompt inputs, but the repository does not wire a complete interactive generation flow in the local demo state. That keeps the example small and explicit, though it leaves room for a richer connected experience later.

Those constraints are reasonable for a project that wants to be inspectable. I would rather have a demo that is limited but honest than a broad example that silently blurs documented API behavior.

Local setup and what the repository supports

The repository includes enough evidence to describe local setup confidently. The README and package.json show a standard Next.js workflow:

npm install
cp .env.example .env.local
npm run dev

A production build is also supported:

npm run build

The environment setup uses OPTAREACH_API_KEY for authenticated server-side requests, and the repository makes it clear that the key is not printed or exposed to the browser.

That is enough to run the app locally and inspect its empty-state behavior, campaign-loading path, and API-client structure. I would keep expectations modest here: the repo is a demo, not a fully scripted deployment guide, so the supported setup is intentionally lightweight.

What I would improve next

If I were extending this project, I would keep the same philosophy and add only changes that preserve the documented boundary.

Some sensible next steps:

wire the form to a real submission flow in the connected deployment
persist the selected campaign instead of always using the first loaded campaign
add a copy-to-clipboard action for generated template output
render more of the returned message-template shape once the exact response structure is confirmed
expand tests around the API client and the error mapper

I would also keep the documentation discipline intact. Any future enhancement should still be tied directly to the documented OptaReach endpoints rather than a guessed workflow.

Takeaway

The biggest lesson from this build is that a good API demo should make the integration feel obvious. You should be able to tell where the request starts, what is sent, how errors are classified, and what the UI does when data is missing.

This project does that well by staying small, server-side, and explicit. It does not try to impress with abstraction. Instead, it shows how to build a clean bridge between a Next.js app and the OptaReach campaign message-template generation flow, which is exactly what I wanted from the start.

How to Build a Snooker Tournament Dashboard with Sportmicro

Miheve — Sat, 26 Sep 2026 13:33:31 +0000

I wanted a snooker dashboard that felt like a real application, not a throwaway API demo.

The goal of this project was simple: build a production-style dashboard around the Sportmicro sports data API, using Next.js, React, and TypeScript, while keeping the integration easy to inspect and extend. Instead of hardcoding data or hiding the provider behind a large abstraction, I treated the app as a practical example of how to work with a snooker tournament dashboard API in a clean, server-side-friendly way.

What made the project interesting to me was the shape of the data itself. Tournaments, seasons, teams, matches, and cup brackets are related, but they do not always arrive in perfect order or with complete fields. That pushed me to design the app around a few core concerns:

keep Sportmicro access in one place
handle loading, empty, and error states explicitly
preserve stable UI behavior even when data is incomplete
make the dashboard readable enough that another developer could extend it without guessing

View the repository

What I built and why I kept the scope narrow

The repository is intentionally focused on one workflow: explore snooker tournament data from Sportmicro and inspect the related records that matter to a developer.

From the README and code, the dashboard currently works with these documented Sportmicro endpoints:

/tournaments
/seasons-by-tournament
/teams-by-tournament
/matches
/cup-bracket

That selection was enough to build a useful demo without pretending to be an exhaustive sports platform. I like this scope because it demonstrates a realistic integration pattern: fetch a list of tournaments, let the user narrow the list, then load detail data for the selected tournament.

The app structure reflects that same constraint. It is not a multi-page product with dozens of views. It is a single dashboard page that prioritizes clarity over feature breadth.

A concise project tree makes that easier to see:

src/
  app/
    error.tsx
    globals.css
    layout.tsx
    loading.tsx
    page.tsx
  lib/
    sportmicro.ts
    tournament-dashboard.ts
tests/
  tournament-dashboard.test.ts

That layout tells the story of the project pretty well: route-level UI in src/app, API access and helpers in src/lib, and tests that focus on the data logic rather than the whole app.

The architecture: keep provider logic out of the UI

The first design decision I made was to separate Sportmicro communication from the page component.

The repository does that in src/lib/sportmicro.ts, which owns:

the Sportmicro base URL
request construction
API key handling through SPORTMICRO_API_KEY
response parsing
basic error normalization

This is the kind of boundary I reach for whenever a project depends on an external API. The UI should know what data it wants, not how each request is assembled.

The client is small but practical. It exposes methods for the documented snooker endpoints and uses a helper to build query parameters only when values are present. That keeps URL construction consistent and avoids clutter in the component layer.

A simplified view of that pattern is visible in the repository:

export function createSportmicroClient(config) {
  return {
    async getTournaments(filters?: { leagueId?: string; classId?: string }) {
      const url = createUrl(baseUrl, '/tournaments', {
        league_id: buildQueryParam('league_id', filters?.leagueId),
        class_id: buildQueryParam('class_id', filters?.classId),
      });
      return requestJson<Tournament[]>(url, config);
    },
    async getMatchesByTournament(tournamentId: string) {
      const url = createUrl(baseUrl, '/matches', {
        tournament_id: buildQueryParam('tournament_id', tournamentId),
      });
      return requestJson<Match[]>(url, config);
    },
  };
}

That pattern gives me two useful benefits:

The page can request a tournament list or tournament details without knowing anything about URL formatting.
Extending the project later means adding another client method rather than scattering fetch logic across the app.

I also appreciate that the project keeps the API key on the server side. The page creates the client from process.env.SPORTMICRO_API_KEY, which matches the repository’s goal of avoiding exposed credentials and using the same configuration model locally and in deployment.

How the dashboard flows from search to detail view

The main page in src/app/page.tsx follows a straightforward flow:

create the Sportmicro client
fetch tournaments
filter them using the search query
select one tournament
fetch its related seasons, teams, matches, and cup bracket data
render the dashboard with explicit state handling

That sequence is easy to read because the file keeps the orchestration in one place. The page component is server-rendered, and it only asks for the data it needs based on the current search params.

The search experience is intentionally modest. The helper in src/lib/tournament-dashboard.ts trims and lowercases the query, then checks a small set of fields:

tournament name
tournament ID
league ID
class ID

That choice felt right for this project because the goal was not to build a complex search system. It was to create a useful browsing experience with almost no extra machinery.

The match list also has one implementation detail worth highlighting: deterministic sorting.

Sports data can arrive with incomplete timestamps, and if a list order shifts from refresh to refresh, the UI starts to feel unstable. The repository avoids that by sorting in layers: known start time first, then status type, then match ID.

Here is the relevant logic:

export function sortMatches(matches: Match[]) {
  return [...matches].sort((a, b) => {
    const aTime = a.start_time ? Date.parse(a.start_time) : Number.NaN;
    const bTime = b.start_time ? Date.parse(b.start_time) : Number.NaN;

    if (!Number.isNaN(aTime) && !Number.isNaN(bTime) && aTime !== bTime) {
      return aTime - bTime;
    }
    if (!Number.isNaN(aTime)) return -1;
    if (!Number.isNaN(bTime)) return 1;

    const aStatus = a.status_type ?? '';
    const bStatus = b.status_type ?? '';
    if (aStatus !== bStatus) return aStatus.localeCompare(bStatus);

    return String(a.id).localeCompare(String(b.id));
  });
}

That is a small function, but it solves a real UX issue: list order should stay predictable even when upstream data is imperfect.

The page also treats loading, empty, and failure as first-class outcomes. If the tournament list cannot load, the UI shows a visible error. If the search returns nothing, it tells the user to adjust the query instead of presenting a blank state. And if a selected tournament has no related records, the summary panel explains that too. That feels appropriate for a dashboard built on live sports data.

Challenges and trade-offs

I did not document a dramatic failure during the build, so the more honest way to frame this section is as a set of constraints I had to design around.

The biggest trade-off was scope. Sportmicro exposes a broader API, but this repository intentionally sticks to a narrow snooker workflow. That means the project is easier to understand, easier to test, and less likely to drift into vague “integration demo” territory.

A few other design constraints shaped the implementation:

Server-side credentials only: the app reads SPORTMICRO_API_KEY on the server, which keeps secrets out of the client bundle.
No invented data: the UI uses actual provider responses and shows empty/error states instead of fabricating records.
No over-engineering: the repo uses small modules and simple helpers instead of introducing a heavy state-management layer.
Explicit boundaries: Sportmicro request logic lives in one file, and UI-friendly filtering/sorting lives in another.

Those choices may sound conservative, but for a sports data dashboard they matter. When the provider response changes or a field is missing, a narrow architecture is easier to reason about than a clever one.

Local setup and what the repository supports

The repository does document how to run the project locally, so I can speak to that part confidently.

The setup is straightforward:

npm install
cp .env.example .env.local
SPORTMICRO_API_KEY=your_sportmicro_api_key_here
npm run dev

The README also shows npm run build and npm test, and the package.json confirms the available scripts:

dev
build
start
test
typecheck

That lines up with the rest of the codebase: a Next.js app with TypeScript, Tailwind CSS, and a small Node test suite. There is no evidence of a more complicated local environment, so I would keep expectations aligned with that simple setup.

If I were reusing this project as a starting point, I would appreciate that the local workflow is minimal. It is just enough to validate the integration without hiding behind a long bootstrap process.

Sensible next improvements

A few future improvements would make sense here, and they follow naturally from the current structure:

Add more documented endpoints where useful: the client is already set up for extension, so additional Sportmicro methods would fit cleanly.
Add runtime validation near the API boundary: the app currently works with typed shapes, but validation would make the edge between raw data and UI even safer.
Cache repeated requests on the server: tournament detail data is a good candidate if the same tournament is revisited often.
Expand the detail view: the repository already fetches seasons, teams, matches, and cup bracket rows, so a richer presentation of those records would be a natural next step.
Broaden tests around the helpers and client boundary: the sort and filter logic is small enough that coverage would stay readable.

I would treat those as evolutions, not prerequisites. The current implementation already does the important part: it demonstrates a real integration pattern without hiding the edges of the API.

Takeaway

What I like most about this project is that it treats sports data as a systems problem, not just a UI problem.

The useful lessons here are not specific to snooker. They are the same ones I would carry into any app that consumes live or semi-live provider data:

keep provider details isolated
make empty and error states visible
sort and filter with the data’s imperfections in mind
keep secrets on the server
build a narrow, understandable first version

That approach makes the dashboard feel durable, even if the API is imperfect or the data is incomplete. And for a developer exploring Sportmicro, that is the real value: a clean reference implementation that shows how to build around a live sports data API without turning the app into a pile of fetch calls.

How to Build a Premier League Live Scores Dashboard with Sportmicro

Miheve — Sat, 26 Sep 2026 10:45:29 +0000

When I started this project, the problem I wanted to solve was narrow but realistic: build a Premier League live scores dashboard that behaves like a real product, not a toy demo. Sports data is messy in ways that generic API examples often ignore. Matches can be live, finished, postponed, or interrupted. Fields can be missing. A response can be empty and still be perfectly valid.

So the goal of this build was not “show some football cards.” It was to create a clean, production-style dashboard that demonstrates how to use Sportmicro in a practical Next.js application, with a data layer that stays reusable and a UI that makes state changes explicit.

If you want to inspect the source, View the repository.

The shape of the app

I kept the architecture intentionally small. The repository is a Next.js app using React, TypeScript, and Tailwind CSS, but the important part is how the responsibilities are split:

src/lib/sportmicro.ts owns Sportmicro-specific data access
src/app/page.tsx focuses on rendering the dashboard
src/app/layout.tsx provides the app metadata and document shell
src/app/page.test.ts and src/lib/sportmicro.test.ts cover the score normalization behavior

That separation matters because sports API code tends to accumulate tiny decisions: how to authenticate, what to do when the API is missing, how to display nullable scores, and how to present status values. I wanted all of that to live in one place instead of leaking into the page component.

The app currently centers on one documented live-data workflow: fetching live Premier League matches and rendering them as cards with status, teams, scores, and kickoff time. The page also includes clear handling for empty and error states, which is where these dashboards often become useful or frustrating.

Sportmicro integration: keep the boundary small

The integration is built around a small client module. That module uses the default base URL https://football.sportmicro.com, reads SPORTMICRO_API_KEY, and exposes a couple of fetch helpers. The live dashboard uses the documented /matches-live endpoint, and the client also includes a getMatchesByDateLeague helper for the /matches-by-date-league endpoint.

That client is doing more than just wrapping fetch. It is the boundary between the UI and the API.

A simplified excerpt shows the pattern:

async function requestJson<T>(path: string, params: Record<string, string | undefined> = {}): Promise<T> {
  const apiKey = process.env.SPORTMICRO_API_KEY;
  if (!apiKey) {
    throw new Error('SPORTMICRO_API_KEY is not configured.');
  }

  const response = await fetch(buildUrl(path, params), {
    headers: {
      Authorization: `Bearer ${apiKey}`
    },
    next: { revalidate: 10 }
  });

  if (!response.ok) {
    throw new Error(`Sportmicro request failed with status ${response.status}.`);
  }

  return (await response.json()) as T;
}

The practical value here is not the syntax. It is the discipline:

the UI never needs to know how authentication works
the UI never needs to know the base URL
missing credentials fail clearly
upstream failures surface as readable errors

That makes the dashboard easier to reason about and easier to extend later. If I add another Sportmicro endpoint, I can do it in the same client without changing the rest of the app’s structure.

Implementation flow: from API response to dashboard state

The app flow is straightforward, but each step exists for a reason.

First, the page calls getLiveMatches() inside the server component. The page starts with an empty array and a nullable error string, then swaps those values depending on the outcome of the request. That gives the UI three meaningful branches: error, empty, and data.

Second, each match is rendered as a card with a status pill, team names, scores, and kickoff time. The page reads fields defensively with fallback text like Home team, Away team, and unknown, which is important because live sports responses are rarely perfectly complete.

Third, scores are normalized before rendering. The project keeps this deliberately boring: null, undefined, and empty string become —, while real values are stringified.

That logic is small enough to be tested directly, which is exactly what I wanted. The tests in the repository confirm two things:

missing values become a placeholder
0 is preserved as a legitimate display value

That second point is subtle but important. In sports interfaces, zero is data. It should never disappear just because it is falsy.

The dashboard UI: simple, responsive, and honest

The dashboard page uses Tailwind CSS for a responsive layout, but I was careful not to let styling distract from the data model. The UI has a headline, a “Live matches” section, and a grid of match cards. There is also a search input in the layout, though the current code shows it as interface scaffolding rather than a fully wired filter.

The most useful part of the UI is not the cards themselves; it is how clearly the page communicates state.

If Sportmicro returns nothing, the dashboard explains that no live matches were returned and that this can be expected when the Premier League is not active or when the configured account has no data available. If the request fails, the page shows an alert-like error message and points the user toward environment variables and API reachability.

That distinction is what makes the app feel like a real integration. Empty is not error. Error is not empty. And a missing API key is neither of those; it is a configuration problem that should be obvious immediately.

I also appreciated the way the app keeps the data visualization restrained. Each card shows:

a status pill
team names
home and away scores
kickoff time
a stable identifier when available

That is enough to demonstrate a usable live scores interface without over-committing to a design that would be hard to evolve.

Local setup and environment configuration

The repository supports a normal local setup, and the evidence in the project makes that part clear.

The README documents the expected workflow:

npm install
cp .env.example .env.local
npm run dev

The app expects SPORTMICRO_API_KEY, and src/types/global.d.ts also defines SPORTMICRO_BASE_URL as an optional environment variable. The client defaults to https://football.sportmicro.com, so local setup stays simple unless you explicitly want to override the base URL.

There are also scripts for build and test:

npm run build
npm test
npm run typecheck

I appreciate that the project keeps setup visible instead of hiding it behind helper scripts. For a developer learning an API integration, that is usually the right trade-off.

Challenges and trade-offs

Because this is a build-focused example, the important constraints were mostly design constraints rather than documented failure stories.

The first trade-off was scope. The repository intentionally focuses on live matches rather than trying to model every possible Sportmicro football endpoint. That keeps the integration honest and easier to understand.

The second trade-off is data handling. The code favors explicit fallbacks over assumptions, which means the UI stays predictable when the API returns missing names, nullable scores, or no matches at all. That is less flashy than complex client logic, but it is much safer for a sports dashboard.

The third trade-off is test coverage. The tests in the repo focus on score normalization, which is a sensible place to start because formatting mistakes are easy to miss and easy to reuse elsewhere.

Project tree

Here is the concise shape of the project:

src/
  app/
    globals.css
    layout.tsx
    page.tsx
    page.test.ts
  lib/
    sportmicro.ts
    sportmicro.test.ts
  types/
    global.d.ts

That tree tells the story pretty well. The app is small, the client is isolated, and the tests sit close to the code they verify.

What I would build next

There are a few natural next steps that fit the current structure without changing the project’s direction:

Expand the dashboard with more documented Sportmicro endpoints, such as fixtures or standings.
Add richer runtime validation for API responses so the app can distinguish more match field shapes safely.
Wire the existing search input into an actual filter model.
Broaden the tests beyond score normalization to cover page states and client behavior.
Add a dedicated section for upcoming matches so the app covers more of the match lifecycle.

I would treat those as future improvements, not as missing pieces. The current project already demonstrates the core integration pattern: fetch live football data, normalize it carefully, and present it in a UI that makes the data state obvious.

Takeaway

The main lesson from this build is that a useful sports dashboard is less about clever UI and more about clear boundaries. Keep the API client separate, treat empty data as a first-class state, normalize the awkward values early, and let the page stay focused on rendering.

That approach made this Sportmicro example feel like a real application rather than a demo glued to an endpoint. If you are building your own football API project, start with one narrow workflow and make that workflow robust before you widen the scope.

How to Build a Sports Data FastAPI Gateway with Sportmicro

Miheve — Sun, 20 Sep 2026 13:19:33 +0000

When I started this project, I wanted a small but realistic way to show how a backend can sit in front of a sports data provider without turning into a thin, leaky proxy. The goal was to build a sports data FastAPI gateway that feels production-style: environment-based configuration, a typed client, explicit resource mapping, and predictable responses for consumers who want to work with Sportmicro data through a clean interface.

The repository is an open-source example of that shape, powered by Sportmicro. It does not try to model the entire upstream API. Instead, it focuses on a practical subset and shows the integration boundary clearly. If you want to inspect the code while reading, View the repository.

Why a gateway instead of a direct proxy

The first thing I wanted to avoid was spreading upstream details throughout the app. When a product talks directly to a sports data API, three things tend to happen quickly:

credentials appear in too many places,
response shapes leak into every layer,
error handling becomes inconsistent.

A gateway solves that by putting the upstream integration behind one service boundary.

In this project, FastAPI is the public interface, but Sportmicro remains the provider behind the scenes. That matters because the application owns the contract it exposes to consumers. The gateway returns a stable, developer-facing payload with a source, endpoint, count, preview items, applied filters, and an optional note when no results are found.

The other practical reason for this shape is that sports data is naturally filter-heavy. A consumer might search by league, season, team, player, match, date, or status type. A gateway gives us one place to define which filters are allowed and how they are translated to the upstream API.

The architecture I used

The repository is intentionally small, but the separation of responsibilities is clear.

app/config.py reads settings from the environment.
app/sportmicro_client.py handles outbound HTTP calls to Sportmicro.
app/services.py maps supported resources to known Sportmicro endpoints.
app/main.py defines the FastAPI app and route behavior.
app/models.py defines the query and response structures.

That split is the core of the implementation.

Configuration stays at the edge

Settings reads SPORTMICRO_API_KEY plus optional base URLs and timeout settings from environment variables. The defaults in the code are already aligned to Sportmicro’s football, basketball, and tennis hosts, and get_settings() is cached with lru_cache(maxsize=1). That means configuration is loaded once and reused.

This is a simple choice, but it keeps secrets out of route handlers and makes the app easier to configure locally. It also gives the gateway a single place to adjust upstream hosts if needed.

The client does one job

The SportmicroClient class is deliberately narrow. It checks that an API key exists, expects an injected HTTP client in this environment, builds a query string, attaches the Bearer token, and raises a SportmicroClientError when something goes wrong.

A small excerpt shows the shape:

headers = {"Authorization": f"Bearer {self._api_key}"}
response = await self._client.get(url, headers=headers)
response.raise_for_status()

That is the right level of responsibility for this layer. It does not try to interpret business rules. It just translates a request into an upstream call and turns low-level failures into a controlled error path.

The service layer owns resource mapping

The service layer is where the gateway becomes opinionated. RESOURCE_MAP explicitly lists supported resource keys such as football-teams, football-players, football-matches, basketball-matches, and tennis-rankings. Each key maps to a SportmicroEndpoint with a source, base URL, and path.

That explicit list is important. Rather than building a generic “forward any path” proxy, the app only exposes resources that are intentionally supported. That keeps the contract understandable and reduces the chance of accidentally promising something the upstream provider does not document.

The service also translates the query object into upstream parameters. It uses order for the sort value, which is a good example of where the gateway is allowed to adapt the API without exposing the upstream shape directly to every caller.

How the request flow works

The main request path is straightforward, and that is part of the point.

The app uses a FastAPI lifespan function to create the client once at startup, store the settings and service on app.state, and close the client on shutdown. From there, route handlers can focus on request and response behavior instead of lifecycle management.

The /resources/{resource} route accepts a set of query parameters:

league_id
season_id
team_id
player_id
match_id
name
date
status_type
limit
offset
lang
sort

These are assembled into a SportmicroQuery, then handed to SportmicroService.list_resource().

From there, the flow is:

check whether the requested resource is supported,
resolve the matching upstream endpoint,
translate the query into upstream parameters,
fetch the list from Sportmicro,
build a response with source, endpoint, count, preview items, filters, and an optional note.

The route also handles errors at the edge. If the client raises SportmicroClientError, the app returns a 502-style JSON response with a detail message and retry_after_seconds: 60. That keeps the gateway honest: the failure is upstream, not local.

One detail I appreciated is the empty-state handling. If Sportmicro returns no items, the gateway does not treat that as an error. Instead, it adds a note suggesting the user widen the search or remove optional filters. For sports data, that is a sensible default because a narrow query is often valid even when it produces nothing.

Data modeling and response shaping

The repository uses dataclasses instead of a heavier schema stack. That keeps the code easy to follow while still providing structure.

SportmicroQuery is the input shape. It includes defaults for pagination and language, and it has a validate() classmethod that rejects unexpected fields. That method is a small guardrail against accidental input drift.

ResourcePreview is the output shape for the preview list. It intentionally selects a limited set of commonly useful fields:

id
name
description
status_type
start_time
league_id
season_id
team_id
player_id
match_id

The service converts raw items into preview objects and then back to dictionaries. That means the API response stays concise even if the upstream payload includes more detail.

I think this is a useful pattern for sports data APIs in general. A gateway does not have to expose every field from the provider. It can present the smallest stable subset that helps clients search, inspect, and decide what to fetch next.

Challenges and trade-offs

The main trade-off here was intentional scope, not a dramatic implementation problem.

The code supports a small, explicit set of resources instead of trying to mirror all Sportmicro endpoints. That choice keeps the gateway accurate and easy to reason about, but it also means the project is not a universal proxy. In practice, that is a feature: the app only exposes the football, basketball, and tennis resources already represented in the repository.

Another constraint is the backend-only design. There is no browser UI, so the repository leans on FastAPI’s OpenAPI docs and JSON responses rather than a frontend experience. That keeps the example focused on integration architecture rather than presentation.

A final design consideration is transport handling. The client expects an HTTP client to be available in the runtime environment, and the repository’s shape suggests the app is built around a controlled async backend context rather than a fully embedded HTTP stack. That keeps the example clean, but it also means the transport boundary matters when you extend or test the app.

Local setup and testing

The repository includes enough evidence to describe local setup safely.

The README shows the expected workflow:

pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

It also documents the required SPORTMICRO_API_KEY environment variable and optional base URLs for football, basketball, tennis, plus a timeout setting. Once the server is running, the API root, /health, and /docs are available locally.

For validation, the repository also documents two useful checks:

python3 -m compileall -q .
python3 -m unittest discover -s tests

That lines up with the presence of a test suite under tests/, which is a good sign that the project is meant to be exercised rather than just read.

Project shape at a glance

Here is the compact structure I kept in mind while building:

app/
  config.py
  main.py
  models.py
  services.py
  sportmicro_client.py
tests/
  test_app.py
  test_client.py
  test_main.py
  test_models.py

That tree is small enough to understand quickly, but it still reflects a real backend boundary: configuration, transport, service logic, and API surface are all separated.

What I would improve next

A few future improvements stand out if you wanted to evolve this gateway further:

add more documented Sportmicro resources to the explicit map,
expand response modeling for endpoints that have stable, known shapes,
add caching where upstream update frequency makes sense,
broaden tests around error paths and empty-state responses,
consider a richer response contract for consumers that need deeper data than the current preview list.

I would keep those as deliberate extensions, not assumptions. The current repository does one thing clearly: it demonstrates how to wrap Sportmicro data in a clean FastAPI gateway without overcomplicating the integration.

Takeaway

The main lesson from this build is that a useful sports data gateway does not have to be large to be valuable. If the configuration is centralized, the client is narrow, the resource mapping is explicit, and the response contract is stable, consumers get something they can actually build against.

That is the part I would reuse in another integration: keep the provider-specific details at the edge, expose only the resources you truly support, and make empty results and upstream failures behave predictably. For sports APIs, that discipline is often more useful than broad surface area.

How to Build a NCAA Football Schedule Tracker with Sportmicro

Miheve — Sun, 20 Sep 2026 12:04:48 +0000

I built this project because sports API demos often stop at “it renders data” and skip the part that actually matters in a real app: what happens when the payload is partial, empty, or unavailable. For an NCAA football schedule tracker, that’s the interesting problem. A schedule browser only feels trustworthy if it can show a clean table, explain loading, and fail gracefully when the provider doesn’t return what you expected.

The goal of this repository was to make a small, production-style React app that demonstrates how to use Sportmicro as a real sports data provider without pretending the project is a full sports platform. If you want to inspect the code alongside this write-up, you can View the repository.

What I set out to prove

The scope is intentionally narrow: browse NCAA football fixtures, filter them by date and keyword, and make the app honest about loading and failure states. That narrowness is the point. It forces the integration decisions to be visible instead of hiding them behind a large feature set.

The app is built around a few principles I wanted to demonstrate:

the API client lives separately from the UI
provider responses are normalized before rendering
environment-based configuration keeps secrets out of the repo
the UI handles loading, empty, and error states explicitly

That combination makes the project more useful than a toy fetch-and-print example. It’s a practical ncaa football schedule tracker API reference for anyone building with an American football API or a broader sports data API.

Architecture: keep the Sportmicro boundary explicit

The code is split into three layers:

src/lib/sportmicroClient.ts handles API access
src/lib/fixtures.ts reshapes raw data for display
src/ui/App.tsx owns page state and rendering

That boundary is the main architectural decision in the repo. It keeps the Sportmicro-specific details out of the React tree, which matters because API integration tends to get messy as soon as you mix request logic, parsing, and UI state in one component.

The client module centralizes authentication and fetch behavior. It uses the American football base URL, reads SPORTMICRO_API_KEY from the environment, and throws a clear error if the key is missing or if Sportmicro responds with a non-2xx status.

A compact excerpt shows the pattern:

async function requestJson<T>(path: string, searchParams: Record<string, string | undefined> = {}): Promise<T> {
  const url = new URL(path, API_BASE_URL);
  Object.entries(searchParams).forEach(([key, value]) => {
    if (value) url.searchParams.set(key, value);
  });

  const response = await fetch(url, {
    headers: {
      Authorization: `Bearer ${getApiKey()}`,
      Accept: 'application/json',
    },
  });

  if (!response.ok) {
    throw new SportmicroError(`Sportmicro request failed with ${response.status} ${response.statusText}`, response.status);
  }

  return (await response.json()) as T;
}

This helper does three useful things:

it keeps the base URL in one place
it injects the API key consistently
it turns provider errors into a message the UI can surface directly

That’s the sort of boundary that pays off later if the provider changes shape. The React code does not need to know how request headers are built or how query params are encoded.

How Sportmicro is integrated

This app uses three Sportmicro endpoints in the current implementation:

GET /leagues
GET /teams-by-league
GET /matches-by-date-league

The client exposes a function for each endpoint, which is a sensible fit for a small schedule browser. The UI loads the three data sets together when the selected date changes, then combines them into one view.

A few implementation choices are worth calling out:

getUpcomingMatches(date) sends league_id=eq.ncaaf and optionally filters by date
getTeamsByLeague(leagueId) requests team data for the chosen league
getLeagues() fetches a short league list for the summary cards

In App.tsx, those calls are coordinated with Promise.all:

const [leagueData, teamData, matchData] = await Promise.all([
  getLeagues(),
  getTeamsByLeague(DEFAULT_LEAGUE),
  getUpcomingMatches(selectedDate),
]);

I like this because the screen stays coherent. Instead of rendering one section immediately and letting the rest trickle in, the app waits until the core data is ready. That makes the page feel more deliberate and easier to reason about.

The authentication path is also intentionally simple: the repo includes .env.example, and the key lives in SPORTMICRO_API_KEY. That keeps secrets out of the repository and makes the setup flow obvious for anyone cloning the project.

Turning raw matches into UI-ready fixtures

The second layer is src/lib/fixtures.ts, which handles normalization and filtering. This file does the unglamorous work that makes the UI simple.

The flow is:

normalizeTeams() turns the team list into a lookup map
resolveFixtures() attaches homeTeam and awayTeam objects to each match
filterFixtures() narrows the list by date and search text

That separation matters because raw API data is rarely shaped for the exact screen you want. In this project, a match may arrive with missing team names or timestamps, so the UI needs sensible fallbacks. The normalized fixture model gives the component display-friendly values like displayDate, displayTime, and statusLabel.

The filter logic shows the kind of practical compromise I wanted:

const teamText = `${fixture.homeTeam?.name ?? ''} ${fixture.awayTeam?.name ?? ''}`.toLowerCase();

The search feature only needs to support team names and fixture IDs, so the helper keeps that logic outside the component tree. That means the React layer stays focused on state and rendering, while the data layer handles the awkward parts of partial provider responses.

What the UI does, and why it stays small

The interface is deliberately modest. It has:

a date picker
a search field
a fixtures table
three summary cards

That’s enough to demonstrate the Sportmicro integration without turning the project into a fake sports portal. The application state in src/ui/App.tsx stays readable:

selectedDate defaults to today
search filters by team name or fixture ID
isLoading and error control the screen state
leagues, teams, and fixtures store the fetched data

The most useful part of the UI is how explicitly it handles the three main states:

Loading: show a loading message while the requests are in flight
Error: surface the message from SportmicroError, including the missing-key case
Empty: explain that no fixtures may exist for the chosen date or filter

That empty state is important. Sports APIs often return valid but sparse data, and the app doesn’t invent records or pretend something is broken just because the date has no matches.

The table itself stays minimal. Each row shows the matchup, date, time, and status. If team data is missing, the UI falls back to the team ID or an “unavailable” label instead of crashing or hiding the row. That’s exactly the kind of defensive rendering I want in a live API demo.

Project tree and local setup

The source layout is compact:

src/
  lib/
    fixtures.ts
    sportmicroClient.ts
  ui/
    App.tsx
  main.tsx
  styles.css
  types.ts

The rest of the repository is standard Vite and TypeScript scaffolding, plus tests and build configuration.

Local setup is supported by the repository, so these steps are safe to follow:

Install dependencies with npm install
Copy .env.example to .env
Add your Sportmicro API key as SPORTMICRO_API_KEY
Run the app with npm run dev

The repository also supports build and test commands:

npm run build
npm test

That matters because it shows the project is not just a live demo with a UI shell. The source is set up to compile, build, and test the integration layer in a repeatable way.

Challenges and trade-offs

I didn’t approach this as a “solve everything” sports app. The design constraints were more practical:

keep the provider boundary explicit
avoid hardcoding secrets
handle partial or missing fields honestly
stay focused on schedule browsing instead of live scoring, standings, or player analytics

Those trade-offs show up in the code. The app uses a limited set of endpoints and a single league filter, and it prefers clear fallback text over inventing data. That keeps the implementation understandable and keeps the UI aligned with what the provider actually returns.

Another trade-off is that the app uses the current data shape from Sportmicro directly, with just enough normalization to make the interface stable. That’s a good fit for a small reference project, even if a larger production app would likely add deeper validation and caching around the API boundary.

What I’d improve next

A few future improvements stand out naturally from the current codebase:

stronger runtime validation of Sportmicro responses
more detailed fixture status presentation
additional NCAA-focused filters
pagination if the selected date returns a larger fixture list

Those are all reasonable next steps, but I’d keep the same architecture if I added them. The client should stay the only place that knows how to talk to Sportmicro, while the UI should remain focused on state and rendering.

If I extended the project further, I’d also consider making the filter experience a little richer without expanding the scope too far. The current version proves the data flow; the next step would be refining how a developer inspects and navigates that data.

Takeaway

The main lesson from this build is simple: a good sports API integration is less about fancy UI and more about treating the provider boundary seriously. In this project, the API client is isolated, the fetched data is normalized, and the UI is honest about loading and empty states.

That combination makes the app useful as both a schedule tracker and a reference implementation. If you’re building against Sportmicro, the pattern here should translate well: keep the request layer small, normalize the response once, and let the UI render only the data it can trust.

Building a Football Fixture MCP Server with Sportmicro API

Miheve — Sat, 19 Sep 2026 19:52:59 +0000

I built this project around a simple problem: football fixture data is easy to query in isolation, but hard to expose cleanly to AI clients without turning the integration into a mess of loosely validated endpoints. My goal with this repository was to create a read-only Model Context Protocol server that lets an MCP client ask grounded questions about football fixtures, match details, incidents, and lineups through the Sportmicro API, while keeping the surface area intentionally small.

That shape matters. Instead of trying to mirror the whole API, I focused on a narrow research layer: enough tools to answer fixture questions reliably, but not so many that the server becomes difficult to reason about or trust. The result is a TypeScript MCP server built with @modelcontextprotocol/sdk, zod, and a typed Sportmicro client.

View the repository

The architecture I used

The implementation is split into three parts:

server.ts defines the MCP tools and validates tool input
sportmicro-client.ts handles HTTP requests to Sportmicro
test/server.test.ts checks validation and error handling without needing a live API call

That separation keeps the MCP layer thin. The server is responsible for turning tool calls into structured responses, but it does not know how to build URLs or authenticate requests. The client owns those HTTP details. That line between “protocol” and “provider integration” is what keeps the code maintainable.

The data flow is straightforward:

An MCP client calls one of the registered tools.
The server validates the input with zod.
The Sportmicro client sends the request with the API key as a Bearer token.
The server returns structured text so the caller can distinguish success from failure.

A small detail I appreciate here is that the server is intentionally read-only. It does not mutate any Sportmicro data, and it only exposes the documented football endpoints needed for fixture research. That keeps the contract predictable for downstream clients.

Why a narrow MCP surface works here

I’ve found that MCP servers can grow too quickly if you expose every upstream endpoint just because it exists. This project takes the opposite approach: expose only the tools that match the actual research workflow.

In this repository, that means five tools:

search_matches_by_date
search_matches_by_date_and_league
get_match_by_id
get_match_incidents
get_match_lineups

That small tool set is enough to answer common football research questions without encouraging speculative behavior. It also makes the server easier to validate. For example, search_matches_by_date requires a date in YYYY-MM-DD format, while search_matches_by_date_and_league adds a league ID and optional pagination fields. Inputs are checked before any upstream request is made, which is exactly what I want in a server that sits between an AI client and a third-party API.

The Sportmicro integration itself is equally focused. The client points at the football API and maps each operation to a documented endpoint:

/matches-by-date
/matches-by-date-league
/matches
/matches-incidents
/matches-lineups

That decision matters because it avoids inventing fields or behavior that aren’t present in the provider documentation. When you’re building an AI-facing integration, being precise is more valuable than being broad.

How the implementation flows

The core implementation lives in src/server.ts. I like how compact it is, because the code reveals the actual contract without a lot of framework noise.

A useful pattern here is the structuredPayload and errorPayload pair. Both return JSON text wrapped in MCP content blocks, which keeps the output machine-readable while still being easy for a client to inspect. The callback wrapper validates input, runs the handler, and converts exceptions into tool-level errors.

Here’s the part that captures that flow:

function buildToolCallback(name: string, spec: ToolSpec) {
  return async (input: unknown) => {
    const parsed = z.object(spec.inputSchema).parse(input);
    try {
      const data = await spec.handler(parsed);
      return structuredPayload(name, data);
    } catch (error) {
      return errorResponse(name, error);
    }
  };
}

What I like about this approach is that it keeps all the tool-specific plumbing in one place. The actual tool registrations become declarative:

define an input schema
connect it to a client method
register the tool with the MCP server

That pattern is repeated for each tool, so the file stays readable even as the server supports multiple research operations.

The client in src/sportmicro-client.ts follows the same principle. It builds a base URL, attaches the API key as Authorization: Bearer ..., and converts non-2xx responses into a custom SportmicroClientError. That gives the server a clean way to distinguish API failures from validation problems.

Project structure at a glance

The repository is intentionally small, which helps a lot when you’re working on a protocol adapter rather than a full product.

src/
  index.ts               Entry point export
  server.ts              MCP server and tool registration
  sportmicro-client.ts   Typed Sportmicro HTTP client
  test/                  Node test files

The rest of the repository supports that core:

README.md documents setup and usage
.env.example shows the required SPORTMICRO_API_KEY
package.json defines the TypeScript build and Node test flow
docs/devto.md contains an article draft for the project

The entry point is also minimal. src/index.ts just re-exports runServer, and the server starts with stdio transport when executed directly. That is exactly what I want for MCP: a small executable surface, not a lot of bootstrapping code.

Testing and local setup

The repository supports a simple local workflow:

Node.js 20 or newer
SPORTMICRO_API_KEY in the environment
npm install
npm run build
npm test
node dist/index.js

Those commands are backed by the project files, so this isn’t speculative setup. The tests use Node’s built-in test runner and are wired to compile before execution through pretest, which means the compiled output is what gets tested.

The tests are also practical. They don’t try to hit the live Sportmicro API. Instead, they verify two things the repository can reliably check on its own:

malformed tool input is rejected before any client call
upstream Sportmicro errors are turned into actionable tool responses

That gives confidence in the contract without depending on network availability or external fixtures.

Challenges and trade-offs

I’d frame this project more as a set of design constraints than a story of runtime surprises. The code clearly reflects a few trade-offs I had to make:

Read-only by design: useful for research, but it means the server is intentionally limited in scope.
Small tool surface: easier to trust and test, but it does not attempt to cover the full Sportmicro API.
Structured JSON text responses: simple for MCP clients to parse, though not as rich as a custom resource model.
Environment-based API key handling: secure and portable, but it requires setup before the server can run.

There’s also a subtle constraint in the client implementation: it only sends query parameters when values are present. That keeps requests tidy, but it also means the server’s schemas need to stay aligned with what the API expects. In a narrow integration like this, that’s a good trade-off because it forces clarity instead of hidden behavior.

What I’d improve next

A few next steps stand out as sensible future improvements:

add richer match-detail tools where the Sportmicro documentation supports them
include more explicit freshness metadata in tool responses
add a small integration-test harness that mocks Sportmicro responses
make the output shape even more descriptive for clients that want to inspect match data programmatically

I’d keep those improvements aligned with the same principle as the current implementation: only add what can be documented, validated, and supported cleanly.

Takeaway

What I like most about this project is that it treats an MCP server as an integration boundary, not a feature dump. The server is small on purpose, the validation is explicit, and the Sportmicro client owns the API details cleanly. That makes the code easier to trust, easier to test, and easier to extend without breaking the contract.

If you’re building a TypeScript MCP server for an external API, this is the pattern I’d recommend: keep the tool surface narrow, validate early, return structured errors, and let the provider client handle the HTTP mechanics. For a read-only football fixture research server, that combination is enough to stay focused while still being useful.

How to Build a NBA Game Odds Monitor with Sportmicro

Miheve — Fri, 18 Sep 2026 20:12:35 +0000

I built this project because sports data demos often look fine in a screenshot and then fall apart the moment the API response is missing a field, the key is absent, or the data simply hasn’t arrived yet. The goal here was narrower and more useful: create a clean NBA game odds monitor that shows how to wire Sportmicro into a React + TypeScript app without hiding the messy parts of real API usage.

The repository is a small but practical example of a nba game odds monitor API workflow. Instead of trying to mimic a full sportsbook, I focused on a developer-facing dashboard that can fetch bookmaker odds, compare markets, refresh on demand, and make loading/error/empty states obvious. That makes it a better learning artifact than a “happy path only” demo.

View the repository

What I set out to build

The project is intentionally scoped around basketball odds data. In the current implementation, the app uses a dedicated Sportmicro client and a React UI to display moneyline odds and bookmaker metadata. The repository README and source show that the app currently centers on:

/odds/bookmakers
/odds/moneyline

That focus matters. A sports data API can expose a lot of surface area, but a useful tutorial usually does better when it shows one complete flow end to end rather than a half-dozen endpoints superficially.

I also wanted the structure to feel production-style even though the app is small. That means:

the UI does not build API URLs directly
the API key is read from environment variables
the app handles loading, empty, and error states explicitly
the response is normalized into a local UI-friendly shape

Those choices keep the demo honest. They also make it easier to extend later without rewriting the whole app.

Architecture: keep the Sportmicro boundary isolated

The cleanest part of the codebase is the separation between the UI and the provider-specific client. The data flow is straightforward:

UI -> app state -> Sportmicro client -> network request -> Sportmicro API

That boundary is implemented in src/sportmicroClient.ts, while src/App.tsx stays focused on state and rendering. I think that split is the right default for any sports developer API integration because it prevents the component tree from becoming a pile of fetch logic and URL assembly.

The client module does three important things:

It chooses a base URL, defaulting to https://basketball.sportmicro.com.
It reads SPORTMICRO_API_KEY from the environment.
It wraps fetch calls into typed helpers.

Here’s the core pattern:

const DEFAULT_BASE_URL = 'https://basketball.sportmicro.com';

function getBaseUrl() {
  return import.meta.env.VITE_SPORTMICRO_BASE_URL || DEFAULT_BASE_URL;
}

async function requestJson<T>(path: string, params?: Record<string, string | undefined>): Promise<T> {
  const apiKey = import.meta.env.SPORTMICRO_API_KEY as string | undefined;
  if (!apiKey) {
    throw { message: 'SPORTMICRO_API_KEY is not set. Add it to your environment before refreshing odds.' } satisfies ApiError;
  }

  const response = await fetch(buildUrl(path, params), {
    headers: { Authorization: `Bearer ${apiKey}` }
  });

  if (!response.ok) {
    throw { message: `Sportmicro request failed with HTTP ${response.status}.`, status: response.status } satisfies ApiError;
  }

  return (await response.json()) as T;
}

The important part is not the syntax; it’s the decision to make the API client the only place that knows about auth headers, base URLs, and response checking. The React app only consumes fetchBookmakers() and fetchOddsForMatch().

That keeps the integration flexible. If I later wanted to add caching, a backend proxy, or a different provider-compatible base URL, the UI would not need to know.

Implementation flow in the UI

The main application logic lives in src/App.tsx, and the flow is deliberately simple.

First, the app loads bookmaker metadata on mount:

useEffect calls fetchBookmakers()
the result populates a local bookmakers state array
if that request fails, the app quietly leaves the filter list empty

Then the user enters a match ID and clicks refresh. The refresh handler checks whether a match ID exists before calling Sportmicro. If the field is empty, the app sets a visible error and stops early.

That guard is a small but important detail. It keeps the app from pretending it can load odds without the one input it actually needs.

After the fetch succeeds, the app normalizes each odds row into a presentation-friendly shape. The normalization happens in a local helper:

function normalizeMarket(row: OddsMarket, index: number): MarketRow {
  return {
    key: [row.bookmaker_id ?? row.bookmaker_name ?? 'unknown', row.market_name ?? 'moneyline', row.selection ?? 'selection', index].join(':'),
    bookmaker: row.bookmaker_name ?? row.bookmaker_id ?? 'Unknown bookmaker',
    market: row.market_name ?? 'Moneyline',
    selection: row.selection ?? 'Unknown selection',
    odd: typeof row.odd === 'number' ? row.odd.toFixed(2) : row.odd ?? '—',
    live: row.is_live ? 'Live' : 'Pre-match',
    updatedAt: row.updated_at ?? 'Unknown'
  };
}

I like this pattern because it does two jobs at once:

it shields the UI from missing API fields
it creates a consistent display model for the table

That’s especially useful with sports data, where the provider may return optional values or varying response shapes. By the time data reaches the table, the app has already decided what “missing” should look like: Unknown, —, or a fallback label.

The UI then uses a single table to display bookmaker, market, selection, odd, state, and updated timestamp. A filter dropdown lets me narrow the view by bookmaker name. That filter is driven by the bookmaker list loaded from Sportmicro, which makes the UI feel connected to the same data source rather than acting like a static mockup.

Project structure at a glance

The tree is compact enough to understand quickly:

src/
  App.tsx             React UI and local state
  sportmicroClient.ts  Sportmicro API client and request helpers
  types.ts             Shared TypeScript types
  main.tsx             React entry point
  styles.css           Global styles

The rest of the repository supports that core flow with Vite, TypeScript, Tailwind config, and test setup. Nothing in the tree feels decorative. Each file has a clear job.

The TypeScript models are intentionally small too:

ApiError
OddsMarket
Bookmaker
MarketRow

That is a sensible choice for a focused odds monitor. I don’t need to model every possible Sportmicro basketball field to make the UI useful. A smaller type surface also makes the tutorial easier to follow, because the app only carries the data it actually renders.

Local setup and how I verified the project shape

The repository supports local development with standard Node tooling. The README documents the expected flow:

npm install
copy .env.example to .env
set SPORTMICRO_API_KEY
run npm run dev
optionally run npm run build and npm run test

That matches the scripts in package.json, which include dev, build, preview, and test.

The setup details matter because the client expects SPORTMICRO_API_KEY to exist before odds can be refreshed. The repository also documents an optional VITE_SPORTMICRO_BASE_URL, which is useful if you want to point the client at a compatible base URL during development.

I also like that the test coverage is modest and honest. The existing test in src/app.test.tsx checks that the app renders the title and the empty state. That may sound small, but it proves the shell of the experience works before any data arrives. For a demo focused on API integration, that is a meaningful baseline.

Challenges and trade-offs

I didn’t treat this project as a place to simulate dramatic failures or invented incidents. The real design constraints are more interesting.

The first trade-off is scope. The app focuses on odds comparison and refresh, not on every Sportmicro basketball endpoint. That keeps the example readable, but it also means the UI is intentionally not a complete sports platform.

The second trade-off is client-side simplicity. The current implementation uses a browser-based client with an environment-provided API key and no server proxy. That makes the demo easy to run and understand, but it also leaves room for future work if stronger credential protection or caching is needed.

The third trade-off is normalization. The app maps provider fields into a smaller MarketRow shape. That keeps rendering predictable, though it means the UI is not trying to preserve every upstream field exactly as returned.

Those are all sensible decisions for an educational repository. They reduce complexity without pretending the problem is simpler than it is.

What I would improve next

A few next steps stand out naturally from the current codebase. I would treat these as future improvements, not existing behavior:

Add another documented odds endpoint and reuse the same client pattern.
Introduce stronger row normalization if more markets are displayed.
Add deduplication based on stable provider IDs if the response shape supports it.
Consider a backend proxy if the app ever needs stricter key handling.
Add caching or a simple refresh policy if repeated requests become expensive.
Expand tests around error handling and filtering behavior.

Those changes would fit the existing architecture well because the provider boundary is already isolated. The point is not to rewrite the app; it is to extend the same pattern carefully.

Takeaway

The main lesson from this build is that a useful sports API demo is less about flashy UI and more about boundaries, fallback states, and a small amount of disciplined normalization. By keeping Sportmicro integration in one client module, using a compact TypeScript model, and making the empty/error/loading states explicit, the app stays understandable even when the data is dynamic.

If I were building another sports developer API example, I’d keep this same recipe: one provider boundary, one clear user action, one narrow data shape, and a UI that tells the truth when the data is not ready yet. That is what makes a demo feel reusable instead of disposable.