Skip to content
This repository was archived by the owner on Dec 12, 2025. It is now read-only.

Commit 45b964b

Browse files
phuctm97phuctm97
committed
Add documentation and package descriptions for public npm packages
Updated Nx to 21.2.2 and added comprehensive README files with installation instructions, API documentation, and usage examples for @modelfetch/bun and @modelfetch/deno packages. Marked @modelfetch/core as internal with guidance to use runtime-specific packages instead.
1 parent 3142431 commit 45b964b

File tree

12 files changed

+368
-69
lines changed

12 files changed

+368
-69
lines changed

‎.cursor/rules/nx-rules.mdc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ alwaysApply: true
66

77
// This file is automatically generated by Nx Console
88

9-
You are in an nx workspace using Nx 21.2.1 and pnpm as the package manager.
9+
You are in an nx workspace using Nx 21.2.2 and pnpm as the package manager.
1010

1111
You have access to the Nx MCP server and the tools it provides. Use them. Follow these guidelines in order to best help the user:
1212

‎.github/instructions/nx.instructions.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ applyTo: '**'
44

55
// This file is automatically generated by Nx Console
66

7-
You are in an nx workspace using Nx 21.2.1 and pnpm as the package manager.
7+
You are in an nx workspace using Nx 21.2.2 and pnpm as the package manager.
88

99
You have access to the Nx MCP server and the tools it provides. Use them. Follow these guidelines in order to best help the user:
1010

‎.nx/version-plans/add-npm-package-documentation.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
__default__: patch
3+
---
4+
5+
Add README and descriptions for public npm packages

‎.nx/version-plans/update-nx-version.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
---
2+
__default__: patch
3+
---
4+
5+
Update Nx from 21.2.1 to 21.2.2

‎libs/modelfetch-bun/README.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# @modelfetch/bun
2+
3+
[![npm version](https://img.shields.io/npm/v/@modelfetch/bun.svg)](https://www.npmjs.com/package/@modelfetch/bun)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
[![GitHub](https://img.shields.io/badge/GitHub-modelfetch-blue)](https://github.com/phuctm97/modelfetch)
6+
7+
Bun runtime adapter for building MCP (Model Context Protocol) servers with ModelFetch.
8+
9+
## Installation
10+
11+
```bash
12+
bun add @modelfetch/bun
13+
```
14+
15+
## Quick Start
16+
17+
```typescript
18+
// server.ts
19+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
20+
import { z } from "zod";
21+
22+
const server = new McpServer({
23+
title: "My Bun MCP Server",
24+
name: "my-bun-server",
25+
version: "1.0.0",
26+
});
27+
28+
server.tool(
29+
"roll_dice",
30+
"Rolls an N-sided dice",
31+
{ sides: z.number().int().min(2) },
32+
({ sides }) => ({
33+
content: [
34+
{
35+
type: "text",
36+
text: `🎲 You rolled a ${1 + Math.floor(Math.random() * sides)}!`,
37+
},
38+
],
39+
}),
40+
);
41+
42+
export default server;
43+
```
44+
45+
```typescript
46+
// index.ts
47+
import handle, { getEndpoint } from "@modelfetch/bun";
48+
import server from "./server";
49+
50+
// Start the server
51+
const bunServer = handle(server);
52+
console.log(`Server running at: ${getEndpoint(bunServer)}`);
53+
```
54+
55+
## API Reference
56+
57+
### `handle(server, options?)`
58+
59+
Starts the MCP server with Bun-specific optimizations and returns a `Bun.Server` instance.
60+
61+
- **server**: The MCP server instance from `@modelcontextprotocol/sdk`
62+
- **options**: Optional `Bun.ServeOptions` (excluding the fetch handler)
63+
64+
Returns: `Bun.Server`
65+
66+
```typescript
67+
const bunServer = handle(server, {
68+
port: 3000,
69+
hostname: "localhost",
70+
});
71+
```
72+
73+
### `getEndpoint(server)`
74+
75+
Gets the MCP server endpoint URL for connecting clients.
76+
77+
- **server**: The `Bun.Server` instance returned by `handle()`
78+
79+
Returns: `string` - The complete endpoint URL
80+
81+
```typescript
82+
const endpoint = getEndpoint(bunServer); // "http://localhost:3000/mcp"
83+
```
84+
85+
## TypeScript Configuration
86+
87+
Bun works with TypeScript out of the box. Recommended `tsconfig.json`:
88+
89+
```json
90+
{
91+
"compilerOptions": {
92+
"target": "ESNext",
93+
"module": "ESNext",
94+
"moduleResolution": "bundler",
95+
"types": ["bun-types"],
96+
"strict": true,
97+
"skipLibCheck": true
98+
}
99+
}
100+
```
101+
102+
## Running Your Server
103+
104+
```bash
105+
# Development
106+
bun run index.ts
107+
108+
# Production (bundled)
109+
bun build index.ts --target=bun --outdir=dist
110+
bun run dist/index.js
111+
```
112+
113+
## Documentation
114+
115+
For complete documentation, examples, and guides, visit [modelfetch.com/docs/runtimes/bun](https://modelfetch.com/docs/runtimes/bun).
116+
117+
## License
118+
119+
MIT

‎libs/modelfetch-bun/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"name": "@modelfetch/bun",
33
"version": "0.0.5",
4+
"description": "Bun runtime adapter for building MCP servers with ModelFetch",
45
"repository": {
56
"type": "git",
67
"url": "git+https://github.com/phuctm97/modelfetch.git",

‎libs/modelfetch-core/README.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# @modelfetch/core
2+
3+
[![npm version](https://img.shields.io/npm/v/@modelfetch/core.svg)](https://www.npmjs.com/package/@modelfetch/core)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
6+
## ⚠️ Internal Package
7+
8+
This is an internal package for ModelFetch. **Do not use this package directly.**
9+
10+
## Use Runtime-Specific Packages Instead
11+
12+
To build MCP servers with ModelFetch, use one of the following runtime-specific packages:
13+
14+
- **[@modelfetch/bun](https://www.npmjs.com/package/@modelfetch/bun)** - For Bun applications
15+
- **[@modelfetch/deno](https://www.npmjs.com/package/@modelfetch/deno)** - For Deno applications
16+
17+
## Documentation
18+
19+
For complete documentation and examples, visit [modelfetch.com](https://modelfetch.com).
20+
21+
## License
22+
23+
MIT

‎libs/modelfetch-core/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"name": "@modelfetch/core",
33
"version": "0.0.5",
4+
"description": "Internal utilities for ModelFetch. Use @modelfetch/bun or @modelfetch/deno instead.",
45
"repository": {
56
"type": "git",
67
"url": "git+https://github.com/phuctm97/modelfetch.git",

‎libs/modelfetch-deno/README.md‎

Lines changed: 144 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,144 @@
1+
# @modelfetch/deno
2+
3+
[![npm version](https://img.shields.io/npm/v/@modelfetch/deno.svg)](https://www.npmjs.com/package/@modelfetch/deno)
4+
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5+
[![GitHub](https://img.shields.io/badge/GitHub-modelfetch-blue)](https://github.com/phuctm97/modelfetch)
6+
7+
Deno runtime adapter for building MCP (Model Context Protocol) servers with ModelFetch.
8+
9+
## Installation
10+
11+
```bash
12+
deno add jsr:@modelfetch/deno
13+
```
14+
15+
## Quick Start
16+
17+
```typescript
18+
// server.ts
19+
import { McpServer } from "npm:@modelcontextprotocol/sdk@^0.7.0/server/mcp.js";
20+
import { z } from "npm:zod@^3.24.1";
21+
22+
const server = new McpServer({
23+
title: "My Deno MCP Server",
24+
name: "my-deno-server",
25+
version: "1.0.0",
26+
});
27+
28+
server.tool(
29+
"roll_dice",
30+
"Rolls an N-sided dice",
31+
{ sides: z.number().int().min(2) },
32+
({ sides }) => ({
33+
content: [
34+
{
35+
type: "text",
36+
text: `🎲 You rolled a ${1 + Math.floor(Math.random() * sides)}!`,
37+
},
38+
],
39+
}),
40+
);
41+
42+
export default server;
43+
```
44+
45+
```typescript
46+
// index.ts
47+
import handle, { getEndpoint } from "jsr:@modelfetch/deno";
48+
import server from "./server.ts";
49+
50+
// Start the server
51+
const httpServer = handle(server);
52+
httpServer.finished.then(() => {
53+
console.log("Server stopped");
54+
});
55+
56+
// Get the server address
57+
const address = httpServer.addr;
58+
if (address) {
59+
console.log(`Server running at: ${getEndpoint(address)}`);
60+
}
61+
```
62+
63+
## API Reference
64+
65+
### `handle(server, options?)`
66+
67+
Starts the MCP server with Deno-specific optimizations and returns a `Deno.HttpServer` instance.
68+
69+
- **server**: The MCP server instance from `@modelcontextprotocol/sdk`
70+
- **options**: Optional `Deno.ServeOptions` for configuring the HTTP server
71+
72+
Returns: `Deno.HttpServer`
73+
74+
```typescript
75+
const httpServer = handle(server, {
76+
port: 3000,
77+
hostname: "localhost",
78+
});
79+
```
80+
81+
### `getEndpoint(address)`
82+
83+
Gets the MCP server endpoint URL for connecting clients.
84+
85+
- **address**: A `Deno.Addr` object from the HTTP server
86+
87+
Returns: `string` - The complete endpoint URL
88+
89+
```typescript
90+
const endpoint = getEndpoint(httpServer.addr); // "http://localhost:3000/mcp"
91+
```
92+
93+
## Running Your Server
94+
95+
```bash
96+
# Development (with all permissions)
97+
deno run -A index.ts
98+
99+
# Production (with specific permissions)
100+
deno run --allow-net index.ts
101+
102+
# Compiled executable
103+
deno compile -A index.ts -o mcp-server
104+
./mcp-server
105+
```
106+
107+
## Permissions
108+
109+
Deno requires explicit permissions. For MCP servers, you typically need:
110+
111+
- `--allow-net`: For the HTTP server
112+
- `--allow-read`: If reading files
113+
- `--allow-write`: If writing files
114+
- `--allow-env`: For environment variables
115+
- `-A`: Allow all (development only)
116+
117+
## Configuration
118+
119+
Optional `deno.json`:
120+
121+
```json
122+
{
123+
"compilerOptions": {
124+
"strict": true
125+
},
126+
"imports": {
127+
"@modelfetch/deno": "jsr:@modelfetch/deno",
128+
"@modelcontextprotocol/sdk": "npm:@modelcontextprotocol/sdk@^0.7.0",
129+
"zod": "npm:zod@^3.24.1"
130+
},
131+
"tasks": {
132+
"dev": "deno run -A index.ts",
133+
"build": "deno compile -A index.ts"
134+
}
135+
}
136+
```
137+
138+
## Documentation
139+
140+
For complete documentation, examples, and guides, visit [modelfetch.com/docs/runtimes/deno](https://modelfetch.com/docs/runtimes/deno).
141+
142+
## License
143+
144+
MIT

‎libs/modelfetch-deno/package.json‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
{
22
"name": "@modelfetch/deno",
33
"version": "0.0.5",
4+
"description": "Deno runtime adapter for building MCP servers with ModelFetch",
45
"repository": {
56
"type": "git",
67
"url": "git+https://github.com/phuctm97/modelfetch.git",

0 commit comments

Comments
 (0)