# https://github.com/open-and-async/mcp Project Manual

Generated at: 2026-07-22 03:26:49 UTC

## Table of Contents

- [Project Overview](#page-1)
- [System Architecture and Code Layout](#page-2)
- [Tools, Resources, and Prompts](#page-3)
- [Data, Deployment, and Operations](#page-4)

<a id='page-1'></a>

## Project Overview

### Related Pages

Related topics: [System Architecture and Code Layout](#page-2), [Tools, Resources, and Prompts](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [README.md](https://github.com/open-and-async/mcp/blob/main/README.md)
- [package.json](https://github.com/open-and-async/mcp/blob/main/package.json)
- [server.json](https://github.com/open-and-async/mcp/blob/main/server.json)
</details>

# 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]()

| Manifest | Ecosystem | Purpose |
|----------|-----------|---------|
| `package.json` | npm | Installation, dependency resolution, binary entry |
| `server.json` | MCP registry | Server identity, configuration, discovery |

## 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:

```mermaid
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.

---

<a id='page-2'></a>

## System Architecture and Code Layout

### Related Pages

Related topics: [Project Overview](#page-1), [Tools, Resources, and Prompts](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/index.js](https://github.com/open-and-async/mcp/blob/main/src/index.js)
- [src/data.js](https://github.com/open-and-async/mcp/blob/main/src/data.js)
- [src/prompts.js](https://github.com/open-and-async/mcp/blob/main/src/prompts.js)
- [src/resources.js](https://github.com/open-and-async/mcp/blob/main/src/resources.js)
- [src/tools/content.js](https://github.com/open-and-async/mcp/blob/main/src/tools/content.js)
- [src/tools/methods.js](https://github.com/open-and-async/mcp/blob/main/src/tools/methods.js)
</details>

# 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.

| File | MCP Primitive | Responsibility |
| --- | --- | --- |
| `src/prompts.js` | Prompts | Declares reusable prompt templates the client can list and render with arguments. |
| `src/resources.js` | Resources | Declares read-only, URI-addressable content the client can fetch. |
| `src/tools/content.js` | Tools (content namespace) | Implements content-oriented tools (e.g. fetching or transforming resource content). |
| `src/tools/methods.js` | Tools (method namespace) | Implements action-oriented tools that mutate state or invoke backend operations. |

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.

```mermaid
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]()

---

<a id='page-3'></a>

## Tools, Resources, and Prompts

### Related Pages

Related topics: [System Architecture and Code Layout](#page-2), [Data, Deployment, and Operations](#page-4)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [src/tools/methods.js](https://github.com/open-and-async/mcp/blob/main/src/tools/methods.js)
- [src/tools/content.js](https://github.com/open-and-async/mcp/blob/main/src/tools/content.js)
- [src/resources.js](https://github.com/open-and-async/mcp/blob/main/src/resources.js)
- [src/prompts.js](https://github.com/open-and-async/mcp/blob/main/src/prompts.js)
- [src/index.js](https://github.com/open-and-async/mcp/blob/main/src/index.js)
</details>

# 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:

| Field | Purpose |
|---|---|
| `name` | Stable identifier used in `tools/call` |
| `description` | Human-readable summary shown to the model |
| `inputSchema` | JSON Schema describing accepted arguments |

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

```mermaid
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.

---

<a id='page-4'></a>

## Data, Deployment, and Operations

### Related Pages

Related topics: [Project Overview](#page-1), [Tools, Resources, and Prompts](#page-3)

<details>
<summary>Related Source Files</summary>

The following source files were used to generate this page:

- [data/book.json.br](https://github.com/open-and-async/mcp/blob/main/data/book.json.br)
- [data/README.md](https://github.com/open-and-async/mcp/blob/main/data/README.md)
- [package.json](https://github.com/open-and-async/mcp/blob/main/package.json)
- [server.json](https://github.com/open-and-async/mcp/blob/main/server.json)
- [smithery.yaml](https://github.com/open-and-async/mcp/blob/main/smithery.yaml)
- [LICENSE](https://github.com/open-and-async/mcp/blob/main/LICENSE)
</details>

# 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:

| File | Role | Consumer |
| --- | --- | --- |
| `package.json` | Build and runtime manifest | npm / Node.js / CI |
| `server.json` | Server schema and launch command | Smithery registry |
| `smithery.yaml` | Deployment descriptor | Smithery registry |
| `data/book.json.br` | Bundled dataset | MCP server runtime |
| `data/README.md` | Dataset documentation | Operators / contributors |
| `LICENSE` | Legal terms | All consumers |

Deployment Flow:

```mermaid
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.

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Pitfall Log

Project: open-and-async/mcp

Summary: 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
- Evidence strength: source_linked
- 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.
- Evidence: capability.host_targets | https://news.ycombinator.com/item?id=48994186

## 2. Capability evidence risk - Capability evidence risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://news.ycombinator.com/item?id=48994186

## 3. Maintenance risk - Maintenance risk requires verification

- Severity: medium
- Evidence strength: source_linked
- 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.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186

## 4. Security or permission risk - Security or permission risk requires verification

- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- 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
- Evidence strength: source_linked
- Finding: no_demo
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=48994186

## 6. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186

## 7. Maintenance risk - Maintenance risk requires verification

- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=48994186

<!-- canonical_name: open-and-async/mcp; human_manual_source: deepwiki_human_wiki -->