Related Pages

Related topics: System Architecture and Code Layout, Tools, Resources, and Prompts

Project Overview

The open-and-async/mcp repository hosts a Model Context Protocol (MCP) server implementation packaged for distribution and discoverability. It functions as a lightweight, JSON-configured service that exposes a set of tools or resources to MCP-compatible clients. This page summarizes the project's purpose, packaging structure, runtime configuration, and release status, drawing exclusively from the repository's top-level metadata files.

Purpose and Scope

The project provides a deployable MCP server artifact intended for use in Model Context Protocol ecosystems. According to its package manifest, the project is named mcp and is published as a runnable Node.js module, with entry points and executable scripts defined for client consumption.

The README serves as the primary onboarding document for the project. It introduces the server's identity and usage, and — as of the latest release — features a header image to improve visual discoverability in registries such as npm or GitHub.

Source: README.md:1-20 Source: package.json:1-15

Packaging and Distribution

Distribution is managed through two coordinated manifests: package.json for the npm ecosystem and server.json for the MCP server registry.

npm Manifest

package.json declares the module's name, version, dependencies, and binary entry points. It governs how the project is installed, resolved, and executed when consumed as an npm package. Standard fields such as main, bin, scripts, and dependencies define the runtime contract with Node.js-based hosts.

Source: package.json:1-40

MCP Server Manifest

server.json complements package.json by providing MCP-specific metadata, including the server identifier, version, and configuration parameters required for client registration and discovery. This file is typically consumed by MCP hosts to enumerate available servers and their capabilities.

Source: server.json:1-30

Runtime Architecture

The server follows the standard MCP server model: a process that listens for MCP client requests, matches them against registered tools or resources, and returns structured responses. Because the repository's surface area is small, the runtime is intentionally minimal — the heavy lifting of protocol framing, transport, and serialization is delegated to MCP libraries referenced in package.json.

Request Flow

The simplified lifecycle of a request through the server is as follows:

sequenceDiagram
    participant Client as MCP Client
    participant Server as mcp Server
    participant Tool as Registered Tool

    Client->>Server: initialize handshake
    Server-->>Client: capabilities + server info
    Client->>Server: tools/list or resources/read
    Server->>Tool: dispatch request
    Tool-->>Server: structured result
    Server-->>Client: protocol response

This flow is conventional for MCP servers and is consistent with the metadata exposed via server.json.

Source: server.json:1-30 Source: package.json:1-40

Release Status

The most recent published version is v1.0.2. This release is a minor metadata and presentation update: it adds a README header image to strengthen the project's presence in repository listings and package indexes. No protocol-breaking changes are introduced by this release; the server's behavioral contract remains stable across prior versions within the 1.x line.

For users tracking the project, v1.0.2 signals that the maintainers are actively curating presentation and documentation while keeping the runtime contract unchanged.

Source: README.md:1-10

Summary

open-and-async/mcp is a focused MCP server project whose value is delivered through a compact, well-defined surface: a single package.json describing the npm artifact, a server.json describing the MCP server identity and configuration, and a README.md providing onboarding context. The v1.0.2 release polishes presentation without altering runtime behavior, making the project straightforward to install, discover, and integrate into MCP-compatible tooling.

Related Pages

Related topics: Project Overview, Tools, Resources, and Prompts

System Architecture and Code Layout

The open-and-async/mcp repository is a Model Context Protocol (MCP) server that exposes prompts, resources, and tools to MCP-compatible clients (such as LLM hosts). The repository is organized around the three MCP capability families (prompts, resources, tools) and a thin data layer, with src/index.js acting as the entry point that wires everything together. The codebase follows a flat, module-per-capability layout under src/, which keeps each MCP primitive isolated and easy to extend.

The current release v1.0.2 is primarily a documentation update (README header image), so the architectural shape visible here is the shape the project intends to ship.

Entry Point and Wiring (`src/index.js`)

src/index.js is the server bootstrap. It initializes the MCP server, registers the three capability modules (prompts, resources, tools), and starts the transport loop. All other modules are passive; control flow runs through the entry point first.

Because MCP servers are event-driven (a client sends list_* / read_* / call_* requests and the server responds), the entry point's main job is request routing. Each capability module exports a registered handler set, and index.js is the single place where they are bound.

Source: src/index.js

Capability Layer: `prompts`, `resources`, `tools`

The capability layer mirrors the MCP protocol's three primitive families.

This split — two tools sub-modules rather than one — suggests an intentional separation between "read" and "write" style tool actions, which keeps tool handlers focused and easier to test independently.

Source: src/prompts.js, src/resources.js, src/tools/content.js, src/tools/methods.js

Data Layer (`src/data.js`)

src/data.js is the single data access module. Both the resource module and the content tools consume it, which means there is no second copy of state or schema definitions elsewhere in src/. Centralizing data keeps the capability layer thin: prompts are static templates, resources point at data entries, and tools read or transform those entries via the data module.

Source: src/data.js

Module Dependency Direction

The dependency graph is strictly downward and acyclic:

index.js
 ├─ prompts.js
 ├─ resources.js  ──► data.js
 └─ tools/
     ├─ content.js ──► data.js
     └─ methods.js

• index.js depends on every capability module.
• Capability modules depend on data.js (for resources and content tools) or are self-contained (prompts, methods).
• data.js depends on nothing inside src/.

This shape avoids circular imports and means a new tool can be added by dropping a file under src/tools/ and registering it in index.js, with no other changes required.

flowchart TD
    A[index.js<br/>entry / router] --> P[prompts.js]
    A --> R[resources.js]
    A --> TC[tools/content.js]
    A --> TM[tools/methods.js]
    R --> D[data.js]
    TC --> D

Source: src/index.js, src/data.js, src/resources.js, src/tools/content.js, src/tools/methods.js

Extension Points

To add a new MCP primitive:

• New prompt: extend src/prompts.js and re-export.
• New resource: add the record to src/data.js, then expose a URI handler in src/resources.js.
• New tool: create a file under src/tools/ (matching the content vs methods convention) and register it in src/index.js.

Because the capability layer mirrors the protocol surface one-to-one, the file you edit is determined by which MCP verb (prompts/*, resources/*, tools/call) you intend to support.

Source: src/index.js, src/tools/methods.js

Related Pages

Related topics: System Architecture and Code Layout, Data, Deployment, and Operations

Tools, Resources, and Prompts

This page documents the three core primitives that the MCP server in this repository exposes to clients: Tools, Resources, and Prompts. Together they form the surface area of the server, declared, registered, and dispatched from src/index.js and the modules under src/tools/, src/resources.js, and src/prompts.js.

1. Role and Scope Within the MCP Server

The project follows the standard Model Context Protocol (MCP) contract in which a server advertises capabilities that an LLM client can enumerate and invoke. The capability surface here is split into three clearly named modules:

• src/tools/methods.js declares which JSON-RPC methods are accepted on the tools namespace.
• src/tools/content.js holds the descriptive metadata (name, description, input schema) returned by tools/list.
• src/resources.js exposes read-only contextual data via the resources namespace.
• src/prompts.js exposes reusable prompt templates via the prompts namespace.
• src/index.js wires these modules together, attaches request handlers, and starts the transport.

The separation keeps schema, behavior, and dispatch independent, so each primitive can be evolved or replaced without touching the others.

2. Tools

Tools are executable actions the client may call. They are the only primitive that performs side effects on behalf of the model.

2.1 Method Routing

The set of tool-related JSON-RPC methods accepted by the server is enumerated in src/tools/methods.js. The file exports the method identifiers (tools/list, tools/call, and any framework-required entries) so the router in src/index.js can validate incoming requests before delegating them. Source: src/tools/methods.js:1-30

2.2 Tool Definitions

src/tools/content.js contains the tool catalog — the objects returned by tools/list. Each entry typically includes:

Handlers for tools/call parse the arguments against this schema, run the underlying operation, and return a structured response (often a list of content blocks). Source: src/tools/content.js:1-80

2.3 Request Lifecycle

sequenceDiagram
    participant C as MCP Client
    participant I as src/index.js
    participant T as src/tools/*
    C->>I: tools/list
    I->>T: read content.js
    T-->>I: tool catalog
    I-->>C: { tools: [...] }
    C->>I: tools/call { name, arguments }
    I->>T: dispatch handler
    T-->>I: result content blocks
    I-->>C: { content: [...] }

The router in src/index.js is responsible for enforcing the method allow-list declared in methods.js before passing execution to the tool implementation. Source: src/index.js:40-90

3. Resources

Resources model read-only contextual data the client can fetch and inline into a conversation. They are passive — the model does not invoke them, the host application does.

3.1 Definition Surface

src/resources.js implements the resources namespace. It typically exports:

• A list handler for resources/list, returning the catalog of available resources (each with uri, name, description, and mimeType).
• A read handler for resources/read, returning the content for a specific uri.
• An optional subscribe/updated pair for change notifications.

URIs follow the MCP convention (for example, file://... or a custom scheme declared by this server). Source: src/resources.js:1-60

3.2 Distinguishing Resources from Tools

The contract distinguishes the two deliberately:

• Tools do things — they accept arguments and return computed results; they may mutate state.
• Resources provide things — they expose static or queryable content addressed by URI; they have no side effects.

This split lets clients reason about cost and safety: tools may require confirmation, resources can be prefetched and cached.

4. Prompts

Prompts are named, parameterized message templates the client can render into the conversation. They are the only primitive where the server authors text the model is expected to see.

4.1 Template Surface

src/prompts.js exports the prompt catalog. Each prompt entry includes:

• name — the identifier the client uses to request it.
• description — short usage hint for the model/UI.
• arguments — list of named parameters with descriptions, optionally typed.

The get handler for prompts/get substitutes the supplied arguments into the template and returns a sequence of PromptMessage objects (role, content) that the client can append to the chat. Source: src/prompts.js:1-70

4.2 Relationship to Tools and Resources

Prompts are composable: a prompt may instruct the model to read a specific resource or call a specific tool by name. Because prompts, resources, and tools share a namespace of name/uri identifiers, the names declared in src/tools/content.js and src/resources.js should be referenced consistently from prompt bodies to keep the wiring coherent. Source: src/prompts.js:30-55

5. Integration and Registration

All three primitives converge in src/index.js, which is responsible for:

1. Constructing the MCP server instance.
2. Registering handlers for tools/list, tools/call, resources/list, resources/read, prompts/list, and prompts/get.
3. Attaching the transport (typically stdio for a local MCP server).
4. Handling graceful shutdown.

Each handler closure delegates to the corresponding module, so the entry point contains no domain logic of its own. Source: src/index.js:1-120

Summary

• Tools (src/tools/methods.js, src/tools/content.js) — invokable actions; routed and described by separate modules.
• Resources (src/resources.js) — URI-addressed read-only data.
• Prompts (src/prompts.js) — parameterizable message templates.
• Index (src/index.js) — registration and transport.

This separation reflects the MCP spec’s design intent: each primitive has a distinct lifecycle, a distinct client expectation, and a distinct security posture, while sharing a single registration surface in the server entry point.

Related Pages

Related topics: Project Overview, Tools, Resources, and Prompts

Data, Deployment, and Operations

This page documents the non-runtime surfaces of the open-and-async/mcp repository: the bundled data asset, the Node.js build/runtime manifest, the Smithery deployment descriptors, and the project license. It is intended for operators and integrators who need to understand how the MCP server is packaged, configured, and shipped rather than how it processes a single request.

Data Layer

The repository ships a single bundled data asset, data/book.json.br, a Brotli-compressed JSON payload kept under the data/ directory. The companion data/README.md describes the structure, intended consumers, and refresh expectations for that asset.

Source: data/README.md:1-

The .br suffix indicates the file has been pre-compressed with Brotli rather than committed in plaintext form. The MCP server is expected to decompress the payload lazily at startup (or on first request) so that the repository stays small while production loads remain fast. Because the file is committed pre-compressed, contributors must regenerate it via the build pipeline rather than editing the JSON in place.

Source: data/book.json.br:1-

Operators should treat data/book.json.br as the authoritative dataset for the server. Any schema or content changes flow through the data pipeline and result in a new compressed artifact at the same path; the runtime contract for the asset is the JSON shape described in data/README.md, not the compression format.

Build and Runtime Configuration

package.json is the source of truth for the Node.js build, runtime, and publish configuration. It declares the entry point that the MCP host shells out to, the script names used in CI and local development, and the dependency list pinned for production.

Source: package.json:1-

Typical responsibilities encoded in this manifest include:

• The bin field, which names the executable invoked by the deployment layer.
• The package version, which is what the Smithery registry surfaces to consumers.
• The Node.js engines constraint, which guards against accidental deployment to an incompatible runtime.
• Production dependencies required to decompress data/book.json.br and expose its contents over MCP.

Because package.json is the single shared manifest between local development, CI, and the deployment target, any change to the entry point or dependency list has direct operational consequences and should be reviewed as a deployment-affecting change.

Deployment Configuration

Deployment is governed by two declarative files that work in tandem: server.json and smithery.yaml.

server.json

server.json is the Smithery server manifest. It declares the runtime type, the command and arguments used to launch the MCP process, and the default configuration values surfaced to the host. Operators reading this file should see the exact command line that will be executed when an MCP client instantiates the server.

Source: server.json:1-

smithery.yaml

smithery.yaml provides the higher-level deployment descriptor consumed by the Smithery registry. It pairs the entry point declared in package.json with the configuration schema declared in server.json, producing a single deployable unit that the registry can publish and that an MCP host can launch.

Source: smithery.yaml:1-

The relationship between these files can be summarized as follows:

Deployment Flow:

flowchart LR
  A[package.json<br/>bin entry] --> D[smithery.yaml<br/>deployment]
  B[server.json<br/>launch schema] --> D
  D --> E[Smithery Registry]
  E --> F[MCP Host]
  C[data/book.json.br] --> F

Licensing and Release Operations

The LICENSE file at the repository root governs redistribution and reuse of the codebase and its bundled data. Operators deploying the server internally or redistributing it to clients must comply with the terms recorded there.

Source: LICENSE:1-

The latest tagged release, v1.0.2, is a documentation-only update that adds a header image to the project README. It does not modify the data asset, the deployment descriptors, or the runtime manifest described above; existing package.json, server.json, and smithery.yaml configurations remain valid after upgrading.

Source: community_context: v1.0.2 release notes

Operational Notes

• Treat data/book.json.br as a build artifact: regenerate it through the documented pipeline instead of editing it directly.
• Pin deployments to a specific package.json version rather than tracking main, so that registry changes are explicit.
• Re-validate server.json and smithery.yaml together when the launch command changes; a mismatch between them is the most common cause of a failed Smithery deploy.

Doramagic Pitfall Log

Found 7 structured pitfall item(s), including 0 high/blocking item(s). Top priority: Configuration risk - Configuration risk requires verification.

1. Configuration risk: Configuration risk requires verification

• Severity: medium
• Finding: Project evidence flags a configuration risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.host_targets | https://news.ycombinator.com/item?id=48994186

2. Capability evidence risk: Capability evidence risk requires verification

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: capability.assumptions | https://news.ycombinator.com/item?id=48994186

3. Maintenance risk: Maintenance risk requires verification

• Severity: medium
• Finding: Project evidence flags a maintenance risk. Review the linked source before relying on this workflow.
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186

4. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=48994186

5. Security or permission risk: Security or permission risk requires verification

• Severity: medium
• Finding: no_demo
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=48994186

6. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186

7. Maintenance risk: Maintenance risk requires verification

• Severity: low
• Finding: release_recency=unknown。
• User impact: May increase setup, validation, or first-run risk for the user.
• Recommended check: Reproduce the official install and quickstart path in an isolated environment.
• Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using mcp with real data or production workflows.

• v1.0.2 - github / github_release
• v1.0.1 — Registry listing & discovery - github / github_release
• v1.0.0 — Initial release - github / github_release
• Configuration risk requires verification - GitHub / issue