Skip to main content
Glama
asokore

pifini-mcp

Pifini MCP

A thin stdio ↔ HTTPS proxy to Pifini's hosted MCP server — real events, reviewed places, and ticket checkout across the Caribbean & Latin America.

If your MCP client supports remote HTTP servers, you don't need this package at all. Connect directly to:

https://pifini.net/api/mcp

That's a stateless Streamable-HTTP endpoint. This package exists only for clients that speak stdio (a local command + JSON-RPC over stdin/stdout) instead. It has no logic of its own — it reads each request from stdin, forwards it verbatim to the hosted endpoint over HTTPS, and writes the response back to stdout. Nothing here is hardcoded, so every method the hosted server supports (initialize, tools/list, tools/call, ...) works automatically without this proxy needing to know what a "tool" even is.

Install

npx pifini-mcp

Or add it to your MCP client's config (Claude Desktop example):

{
  "mcpServers": {
    "pifini": {
      "command": "npx",
      "args": ["-y", "pifini-mcp"]
    }
  }
}

Related MCP server: @inbin/mcp

What Pifini's MCP server does

  • search_events / get_event — search and read real festivals, carnivals, concerts, and cultural events, strongest coverage in the Caribbean and Latin America.

  • search_places / get_place — search reviewed restaurants, bars, venues, attractions, and professionals, including their published reviews.

  • create_ticket_checkout — generate a Stripe-hosted payment link for event tickets. The agent hands the link to its human, who completes payment themselves — agents never see card details.

Read tools are open; no API key required. Full documentation, tool schemas, and a live example live at pifini.net/agents.

Why a proxy package exists at all

Pifini's server is closed-source and hosted (it's part of a larger commercial application), so there's no public repository to point an MCP client's stdio launcher at directly. This package is that missing piece: a small, genuinely open-source (MIT), auditable bridge — not a stand-in for real server code, just the stdio transport Pifini's hosted server doesn't speak natively.

It holds no API keys, no database access, and no business logic. Every request it receives is forwarded byte-for-byte to https://pifini.net/api/mcp (or the URL in PIFINI_MCP_URL, if you want to point it somewhere else for testing) and the response is passed back unmodified.

License

MIT — see LICENSE.

Available Tools

6 tools
create_ticket_checkoutCreate ticket checkout linkA

Create a secure Stripe-hosted payment link for event tickets. Returns a checkout URL — give it to the human to complete payment themselves; tickets with QR codes are emailed after payment. Get ticket_type_id values from get_event. Always confirm the exact tickets and total with the human before calling this.

ParametersJSON Schema
NameRequiredDescriptionDefault
itemsYesTicket selections
buyer_nameNoBuyer's name (optional)
event_slugYesEvent slug
buyer_emailYesEmail to deliver tickets to (required — ask the human)

Output Schema

ParametersJSON Schema
NameRequiredDescription
eventNo
totalNo
currencyNo
order_idNo
checkout_urlNo
instructionsNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that tickets are emailed after payment and that the checkout is Stripe-hosted. Annotations only indicate non-read-only and non-destructive, so description adds meaningful behavioral context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with zero waste, front-loaded with purpose and outcome, followed by usage guidance. Highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity of a payment tool requiring human confirmation, the description fully covers purpose, input parameter sources, output (URL), and post-payment flow. Output schema exists per context, so no gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, but description adds value: explains where to get ticket_type_id (from get_event), specifies quantity range (1-20 not in schema), and flags buyer_email as required with instruction to ask human.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it creates a Stripe-hosted payment link for event tickets and returns a checkout URL. Distinguished from sibling tools (search/get events, places) which are about information retrieval, not payment.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly instructs to confirm details with the human before calling and to give the URL for self-serve payment. Does not mention when not to use, but context with sibling tools makes it clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_eventGet event detailsA
Read-onlyIdempotent

Full details for one event by slug: description, venue, date/time, and available ticket types with prices and remaining stock. Use the slug from search_events.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesEvent slug from search_events

Output Schema

ParametersJSON Schema
NameRequiredDescription
urlNo
cityNo
slugNo
priceNo
titleNo
countryNo
ends_atNo
summaryNo
websiteNo
categoryNo
currencyNo
starts_atNo
descriptionNo
entry_modelNo
ticket_typesNo
location_nameNo
organizer_urlNo
attendee_countNo
organizer_nameNo
cover_image_urlNo

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. The description adds value by detailing the response contents (available ticket types, prices, remaining stock), which is beyond what annotations cover. No contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no extraneous words. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple one-parameter tool with an output schema, the description adequately covers the return contents and usage context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 100% schema coverage, baseline is 3. The description adds useful context by specifying the slug source ('from search_events'), enhancing the schema's 'Event slug from search_events' description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get') and resource ('event details'), and lists specific data returned (description, venue, date/time, ticket types with prices and stock). It distinguishes from sibling tools like search_events (list) and get_place (different entity).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly mentions using the slug from search_events, providing clear context for when to use this tool. Although it doesn't specify when not to use, the sibling tools list makes alternatives obvious.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_placeGet place details + reviewsA
Read-onlyIdempotent

Full details for one place by slug, including its most recent published reviews if any exist. listing_type distinguishes a curated entry from an unreviewed directory listing (see search_places) — recent_reviews is often an empty array, which means no reviews yet, not a low-quality place. Use the slug from search_places.

ParametersJSON Schema
NameRequiredDescriptionDefault
slugYesPlace slug from search_places

Output Schema

ParametersJSON Schema
NameRequiredDescription
urlNo
cityNo
nameNo
slugNo
typeNo
addressNo
countryNo
summaryNo
websiteNo
categoryNo
avg_ratingNo
price_tierNo
descriptionNo
is_verifiedNo
is_sponsoredNo
listing_typeNo
review_countNo
recent_reviewsNo

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds value beyond annotations by specifying what data is returned (full details, recent reviews) and clarifying field meanings (listing_type, recent_reviews). Annotations already indicate read-only, idempotent, and non-destructive behavior, and the description aligns with them without contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise—two to three sentences—front-loaded with the primary purpose, followed by necessary clarifications. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple tool (one required parameter, well-documented schema, annotations, and an output schema), the description covers all necessary aspects: what it does, how to use it (slug from search_places), and key interpretation details (listing_type, empty reviews). It is complete for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter, slug, is fully described in the schema with 'Place slug from search_places,' and the description repeats 'Use the slug from search_places.' Since schema coverage is 100%, the description adds no new semantic information, meeting the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves full details for one place by slug, including recent reviews, and distinguishes itself from search_places by specifying that the slug comes from that tool. The title 'Get place details + reviews' reinforces the purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly instructs to 'Use the slug from search_places,' providing clear context for when to use this tool. It also addresses a common misinterpretation about empty recent_reviews. While it does not explicitly list when not to use it or name alternatives like get_event, the guidance is sufficient for an agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_categoriesList place categoriesA
Read-onlyIdempotent

Discover valid category values for search_places. Pifini's places directory uses Overture Maps' taxonomy — over 1,000 specific values like caribbean_restaurant, church_cathedral, landmark_and_historical_building — rather than broad buckets, so guessing a category string will usually miss. Call this first with a rough query (e.g. 'coffee' or 'beach') to find the exact value, then pass it to search_places' category parameter.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax results, 1-100 (default 30)
queryNoRough term to match against category values, e.g. 'coffee', 'beach'
countryNoISO-3166 alpha-2 country code — only return categories present in that country

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
categoriesYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, destructiveHint=false. The description adds valuable behavioral context: it uses Overture Maps taxonomy with over 1,000 specific values, and that guessing will usually miss. This explains why the tool is needed and what it returns, beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph but is front-loaded with the purpose, followed by context and usage instruction. Every sentence adds value; no fluff. It is appropriately sized for the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists (so return values are covered), the description is complete. It explains why the taxonomy is needed, how to use the tool, and how to pass results to search_places. The only minor gap is no explicit mention of 'limit' behavior, but schema covers that. Overall comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so each parameter has a schema description. The description adds meaning by explaining that 'query' is a 'rough query' (partial match) and that 'country' filters by country presence. This aids understanding beyond raw schema, though the description does not detail every parameter.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool's purpose: 'Discover valid category values for search_places.' It uses a specific verb (discover) and resource (category values), and distinguishes itself from sibling tools like search_places by acting as a preparatory step. Examples of specific category values further clarify the scope.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly tells when to use: 'Call this first with a rough query... then pass it to search_places' category parameter.' It contrasts with guessing, providing clear context for usage. No alternative tool is mentioned, but the recommendation is direct and actionable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_eventsSearch eventsA
Read-onlyIdempotent

Search upcoming events (festivals, carnivals, concerts, food + cultural events) across the Caribbean, Latin America, and beyond. Returns event names, dates, locations, category, price (when known), and page URLs. Strongest coverage: Barbados, Trinidad, Jamaica, Bahamas, Mexico.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityNoCity name filter
limitNoMax results, 1-50 (default 10)
queryNoFree-text search over title and description
offsetNoSkip this many matching results (for paging past the limit)
countryNoISO-3166 alpha-2 country code, e.g. BB, TT, JM
categoryNoFilter by event category
near_latNoLatitude to search near (pair with near_lng)
near_lngNoLongitude to search near (pair with near_lat)
radius_kmNoSearch radius in km around near_lat/near_lng (default 25, max 500)
entry_modelNoFilter by how someone gets in: 'free' = confirmed free entry, 'ticketed' = Pifini sells tickets, 'external' = paid but sold elsewhere, 'mixed' = umbrella event with both free and paid components, 'unknown' = not yet confirmed either way.
include_pastNoInclude past events (default false)
starts_afterNoOnly events starting on/after this date, e.g. '2026-08-01' or a full ISO timestamp
starts_beforeNoOnly events starting on/before this date, e.g. '2026-08-31' or a full ISO timestamp

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYesNumber of events in this page of results
eventsYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint, idempotentHint, destructiveHint; description adds coverage strengths and output fields. It does not mention default pagination or that past events are excluded by default (handled via schema). Adds context beyond annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences: scope, return fields, coverage. No fluff, front-loaded with core purpose. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given complex schema (13 params, 2 enums, output schema, annotations), the description covers overall function, return fields, and regional strengths. Lacks explicit note on default date-range behavior but schema handles it. Good for the complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

All 13 parameters are already described with schema descriptions (100% coverage). The description adds minimal extra meaning (only geographical strength hint). Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verbs ('search upcoming events') and resource ('events'), listing return fields and geography. It clearly distinguishes from siblings like get_event (single event) and search_places (places).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description states when to use (searching upcoming events in covered regions) but does not explicitly exclude cases or name alternatives; the context of sibling tool names provides implicit differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_placesSearch places and businessesA
Read-onlyIdempotent

Search Pifini's places directory across the Caribbean and Latin America — restaurants, bars, beaches, attractions, venues, hotels, tour operators, professionals, and services. Every result carries listing_type: 'curated' is a small, editorially reviewed set of flagship entries; 'directory' is the much larger set sourced from open map data (name, category, location, contact info) that has no reviews yet — say so rather than implying a recommendation the data doesn't back up. Category is a specific Overture taxonomy value (e.g. caribbean_restaurant, church_cathedral), not a broad bucket — call list_categories first if unsure of the exact value. Results marked is_sponsored are paid placements — disclose that when recommending.

ParametersJSON Schema
NameRequiredDescriptionDefault
cityNoCity name filter
limitNoMax results, 1-50 (default 10)
queryNoFree-text search over name and summary
offsetNoSkip this many matching results (for paging past the limit)
countryNoISO-3166 alpha-2 country code
categoryNoFilter by exact category value (e.g. 'caribbean_restaurant'). Use list_categories to discover valid values — there are 1,000+, not a small fixed set.
near_latNoLatitude to search near (pair with near_lng)
near_lngNoLongitude to search near (pair with near_lat)
radius_kmNoSearch radius in km around near_lat/near_lng (default 25, max 500)
entity_typeNoFilter by broad type of place

Output Schema

ParametersJSON Schema
NameRequiredDescription
countYes
placesYes

TDQS

A4.3/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint and idempotentHint. The description enriches transparency by detailing result types (curated vs. directory) and the need to avoid implying recommendations for directory entries, plus disclosure of sponsored placements. No contradiction with annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that conveys purpose and key nuances. It is front-loaded and efficient, though slightly verbose. Could be streamlined but avoids unnecessary fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (10 params, output schema exists), the description covers critical behavioral aspects (listing types, sponsored results) and refers to list_categories. It does not explain pagination parameters in detail, but schema covers that. Acceptably complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already explains all parameters. The description adds only minor extra context (e.g., repeating the list_categories suggestion for category) but does not significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches Pifini's places directory across the Caribbean and Latin America, listing specific categories (restaurants, bars, etc.). It distinguishes itself from siblings like search_events, get_place, and list_categories by focusing on places search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear usage guidance: advises calling list_categories before using the category filter and discloses how to handle sponsored results. However, it does not explicitly state when not to use this tool (e.g., for events) or name alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updates
    • First observedcreate_ticket_checkout
    • First observedget_event
    • First observedget_place
    • First observedlist_categories
    • First observedsearch_events
    • First observedsearch_places

TDQS

A4.6/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a distinct function: searching vs. getting details for events and places, listing categories, and creating a checkout. There is no overlap or ambiguity between any pair of tools.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case: search_events, get_event, search_places, get_place, list_categories, create_ticket_checkout. This makes the surface predictable and easy to navigate.

Tool Count5/5

With 6 tools, the set is well-scoped for the server's purpose—covering both events and places with search, detail retrieval, and a checkout action. It is neither too sparse nor overly dense.

Completeness5/5

The tools cover the full consumer workflow: discover events/places, get full details, and purchase tickets. The supporting list_categories tool fills a potential gap in place search. No obvious missing operations for the stated domain.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • A
    license
    Not graded
    quality
    B
    maintenance
    A thin stdio proxy to Quantustik's hosted MCP server, providing live S&P 500 signals, forecasts, and market data for MCP clients that only support local stdio servers.
    27 npm
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Proxies stdio MCP clients to Inbin's remote MCP endpoint, exposing tools to list inboxes, search and retrieve events, and inspect schemas.
    16 npm
    1
    MIT
  • A
    license
    C
    quality
    B
    maintenance
    Minimal MCP server exposing the Connectif HTTP API to MCP clients over stdio, enabling operations like contacts, purchases, products, exports, imports, workflows, and more.
    12
    3 npm
    MIT
  • A
    license
    A
    quality
    A
    maintenance
    Zero-dependency stdio bridge to Moltline Studio's fleet of 14 hosted MCP servers covering code review, time operations, data transforms, business ops, education, research, outreach and more. Free tier requires no registration; premium tools unlock with a license. Independently audited, MCPize Verified A.
    2
    10
    MIT