mcp-context-card 1.1.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (18) hide show
  1. package/.well-known/fafa +1 -1
  2. package/AGENTS.md +1 -1
  3. package/CHANGELOG.md +23 -0
  4. package/README.md +7 -2
  5. package/dist/bin.d.ts +1 -1
  6. package/dist/constants.d.ts +1 -1
  7. package/dist/constants.js +1 -1
  8. package/dist/server.js +18 -0
  9. package/docs/MECHANISMS.md +1 -1
  10. package/docs/card-dark.html +2 -2
  11. package/docs/card-light.html +2 -2
  12. package/docs/card.html +2 -2
  13. package/docs/img/card-dark.png +0 -0
  14. package/docs/img/card-identity.png +0 -0
  15. package/docs/img/card-light.png +0 -0
  16. package/docs/index.html +2 -2
  17. package/package.json +1 -1
  18. package/server.json +2 -2
package/.well-known/fafa CHANGED
@@ -9,7 +9,7 @@ agent:
9
9
  name: "mcp-context-card"
10
10
  displayName: "mcp-context-card"
11
11
  vendor: "io.github.Wolfe-Jam"
12
- version: "1.1.0"
12
+ version: "1.1.1"
13
13
  description: >-
14
14
  The essential MCP components for a project's context (AGENTS.md),
15
15
  cross-session memory, and identity — a base MCP on its own, or a
package/AGENTS.md CHANGED
@@ -15,7 +15,7 @@ connection.
15
15
  npm ci
16
16
  ```
17
17
 
18
- Node 22 or newer. No other system dependencies.
18
+ Node 20 or newer. No other system dependencies.
19
19
 
20
20
  ## Build
21
21
 
package/CHANGELOG.md CHANGED
@@ -2,6 +2,29 @@
2
2
 
3
3
  All notable changes to this project. Adheres to [Semantic Versioning](https://semver.org).
4
4
 
5
+ ## 1.1.1
6
+
7
+ Every tool now says what it is and what it does to your project.
8
+
9
+ Each of the nine tools carries a human-readable `title` and MCP tool
10
+ annotations, so a host can label it properly and decide whether to ask
11
+ before running it:
12
+
13
+ - **Read-only (7):** `read_agents_md`, `list_agents_md_sections`,
14
+ `author_agents_md` (returns a draft, writes nothing), `recall`, `whoami`,
15
+ `list_context_sources`, `render_context_card`.
16
+ - **Writes the memory file (2):** `remember` and `forget` are marked
17
+ `destructiveHint: true`. `remember` replaces a fact when an id is reused;
18
+ `forget` removes one.
19
+ - All nine are `idempotentHint: true` (repeating a call changes nothing more)
20
+ and `openWorldHint: false` (they only touch the local project).
21
+
22
+ A new test checks every tool's title and hints against what it actually does,
23
+ so a tool added later can't ship without them. 106 tests, all green on
24
+ Linux, macOS, and Windows.
25
+
26
+ No API change to the nine tools: same names, same inputs, same behaviour.
27
+
5
28
  ## 1.1.0
6
29
 
7
30
  The card scans in one screen — AGENTS.md sections collapse by default.
package/README.md CHANGED
@@ -193,6 +193,10 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
193
193
  | `list_context_sources` | what this project publishes, in what media types, via which surface |
194
194
  | `render_context_card` | the whole card as one self‑contained HTML page (also `GET /card`) |
195
195
 
196
+ Seven tools only read. `remember` and `forget` write the memory file, so they're
197
+ marked destructive and a host can ask before running them. Every tool carries a
198
+ title and MCP tool annotations.
199
+
196
200
  ## The demo
197
201
 
198
202
  `npm run demo` runs every tool over both transports:
@@ -205,10 +209,11 @@ The wire‑level detail is in [docs/MECHANISMS.md](./docs/MECHANISMS.md).
205
209
  4. **Discovery** — `list_context_sources()`, then the same server over stateless
206
210
  HTTP with its `.well-known` routes and `GET /card`.
207
211
 
208
- 104 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
212
+ 106 tests on Linux, macOS, and Windows, coverage‑gated in CI. Two spawn a real
209
213
  child process and check a remembered fact survives the restart — one against
210
214
  an existing `project.fafm`, one starting from a project that has never had
211
- one; another checks the stdio and HTTP tool surfaces match.
215
+ one; another checks the stdio and HTTP tool surfaces match, and another checks
216
+ every tool's title and behaviour hints against what it actually does.
212
217
 
213
218
  ## Layout
214
219
 
package/dist/bin.d.ts CHANGED
@@ -8,7 +8,7 @@ export interface Launch {
8
8
  root: string;
9
9
  }
10
10
  /** what a bare `--help` / `help` prints. */
11
- export declare const HELP = "mcp-context-card 1.1.0\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n mcp-context-card stdio MCP server \u2014 what an MCP host spawns (default)\n mcp-context-card --http stateless Streamable HTTP on PORT (default 3000)\n mcp-context-card --stdio force stdio even when PORT is set\n mcp-context-card card this dir's context card \u2014 opens it in your browser\n at a terminal; HTML to stdout when piped ( > f.html )\n --theme light|dark --accent #hex\n --expanded (all sections open) --stdout\n mcp-context-card --help this text\n mcp-context-card --version print version\n\nENV\n MCP_CONTEXT_CARD_ROOT read AGENTS.md / project.fafm / .well-known/ from here\n PORT if set, run HTTP instead of stdio\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
11
+ export declare const HELP = "mcp-context-card 1.1.1\nServe a project's context (AGENTS.md), memory, and identity over MCP.\n\nUSAGE\n mcp-context-card stdio MCP server \u2014 what an MCP host spawns (default)\n mcp-context-card --http stateless Streamable HTTP on PORT (default 3000)\n mcp-context-card --stdio force stdio even when PORT is set\n mcp-context-card card this dir's context card \u2014 opens it in your browser\n at a terminal; HTML to stdout when piped ( > f.html )\n --theme light|dark --accent #hex\n --expanded (all sections open) --stdout\n mcp-context-card --help this text\n mcp-context-card --version print version\n\nENV\n MCP_CONTEXT_CARD_ROOT read AGENTS.md / project.fafm / .well-known/ from here\n PORT if set, run HTTP instead of stdio\n\nA bare run is an stdio server: it waits for a host to speak JSON-RPC on stdin,\nso it looks idle at a terminal. Try `card` (opens your context in a browser) or `--http`.\nhttps://github.com/Wolfe-Jam/mcp-context-card\n";
12
12
  /**
13
13
  * Decide how to launch, from argv + env. Pure — so the mode matrix is unit
14
14
  * tested without spawning a process.
package/dist/constants.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Server identity constants, in their own module so any file can import
2
2
  * them without pulling in the whole server. */
3
3
  export declare const NAME = "mcp-context-card";
4
- export declare const VERSION = "1.1.0";
4
+ export declare const VERSION = "1.1.1";
5
5
  export declare const SERVER_CARD_URI = "mcp-context-card://server-card";
package/dist/constants.js CHANGED
@@ -1,5 +1,5 @@
1
1
  /** Server identity constants, in their own module so any file can import
2
2
  * them without pulling in the whole server. */
3
3
  export const NAME = "mcp-context-card";
4
- export const VERSION = "1.1.0";
4
+ export const VERSION = "1.1.1";
5
5
  export const SERVER_CARD_URI = "mcp-context-card://server-card";
package/dist/server.js CHANGED
@@ -82,6 +82,8 @@ export function createServer(root = ROOT) {
82
82
  tools: [
83
83
  {
84
84
  name: "read_agents_md",
85
+ title: "Read AGENTS.md",
86
+ annotations: { title: "Read AGENTS.md", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
85
87
  description: "Return this project's AGENTS.md — the whole file, or one section by heading. The instructions a client would otherwise have to know to look for and read wholesale.",
86
88
  inputSchema: {
87
89
  type: "object",
@@ -95,16 +97,22 @@ export function createServer(root = ROOT) {
95
97
  },
96
98
  {
97
99
  name: "author_agents_md",
100
+ title: "Draft an AGENTS.md",
101
+ annotations: { title: "Draft an AGENTS.md", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
98
102
  description: "Author an AGENTS.md for this project and return the draft — BETTER from repo facts alone (via agents-md-facts: real build/test commands, entry points, toolchain conventions, nothing invented), or BEST when a project.faf exists (facts plus its structured goal/who/why as a second managed block ahead of them). Does not write a file.",
99
103
  inputSchema: { type: "object", properties: {} },
100
104
  },
101
105
  {
102
106
  name: "list_agents_md_sections",
107
+ title: "List AGENTS.md Sections",
108
+ annotations: { title: "List AGENTS.md Sections", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
103
109
  description: "List the headings in this project's AGENTS.md, so a client can pull one section instead of spending context on the whole file.",
104
110
  inputSchema: { type: "object", properties: {} },
105
111
  },
106
112
  {
107
113
  name: "remember",
114
+ title: "Remember a Fact",
115
+ annotations: { title: "Remember a Fact", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
108
116
  description: "Persist a fact past the session boundary — written to a .fafm file, not held in memory. Reusing an existing id replaces that fact's text in place (no duplicate); a new id appends. Facts are written verification_status: unverified.",
109
117
  inputSchema: {
110
118
  type: "object",
@@ -123,6 +131,8 @@ export function createServer(root = ROOT) {
123
131
  },
124
132
  {
125
133
  name: "recall",
134
+ title: "Recall a Fact",
135
+ annotations: { title: "Recall a Fact", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
126
136
  description: "Retrieve a fact stored in a previous session by id. Exact lookup — not fuzzy or substring.",
127
137
  inputSchema: {
128
138
  type: "object",
@@ -137,6 +147,8 @@ export function createServer(root = ROOT) {
137
147
  },
138
148
  {
139
149
  name: "forget",
150
+ title: "Forget a Fact",
151
+ annotations: { title: "Forget a Fact", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
140
152
  description: "Remove a fact by id — to correct or drop something stale. A missing id is reported, not an error.",
141
153
  inputSchema: {
142
154
  type: "object",
@@ -151,16 +163,22 @@ export function createServer(root = ROOT) {
151
163
  },
152
164
  {
153
165
  name: "whoami",
166
+ title: "Who Am I",
167
+ annotations: { title: "Who Am I", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
154
168
  description: "This server's own identity — name, vendor, version, status, license — from its .fafa card.",
155
169
  inputSchema: { type: "object", properties: {} },
156
170
  },
157
171
  {
158
172
  name: "list_context_sources",
173
+ title: "List Context Sources",
174
+ annotations: { title: "List Context Sources", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
159
175
  description: "What context does this project publish (AGENTS.md, memory, identity), in what media types, and through which discovery surface. For a client connecting cold.",
160
176
  inputSchema: { type: "object", properties: {} },
161
177
  },
162
178
  {
163
179
  name: "render_context_card",
180
+ title: "Render Context Card",
181
+ annotations: { title: "Render Context Card", readOnlyHint: true, idempotentHint: true, openWorldHint: false },
164
182
  description: "Render the whole card — identity, AGENTS.md, memory, discovery — as one self-contained HTML page a person can read or screenshot. AGENTS.md sections collapse by default; pass expanded:true for the full render. Also served at GET /card (?expand=all) over the HTTP transport.",
165
183
  inputSchema: {
166
184
  type: "object",
package/docs/MECHANISMS.md CHANGED
@@ -29,7 +29,7 @@ Both return:
29
29
  ```jsonc
30
30
  {
31
31
  "name": "mcp-context-card",
32
- "version": "1.1.0",
32
+ "version": "1.1.1",
33
33
  "_meta": {
34
34
  "io.github.Wolfe-Jam.mcp-context-card/context": {
35
35
  "source": "AGENTS.md",
package/docs/card-dark.html CHANGED
@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
100
100
  <main class="card">
101
101
  <div class="top">
102
102
  <h1>mcp-context-card</h1>
103
- <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
103
+ <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
104
104
  </div>
105
105
  <section>
106
106
  <p class="label">Context — AGENTS.md</p>
@@ -108,7 +108,7 @@ details.ctx-section>.md{padding:0 0 16px}
108
108
  <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
109
109
  <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
110
110
  <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
111
- <p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
111
+ <p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
112
112
  npm run typecheck # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test # node:test — every test/*.test.ts
113
113
  npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
114
114
  npm run demo # end to end: all tools over stdio, then over stateless HTTP
package/docs/card-light.html CHANGED
@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
100
100
  <main class="card">
101
101
  <div class="top">
102
102
  <h1>mcp-context-card</h1>
103
- <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
103
+ <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
104
104
  </div>
105
105
  <section>
106
106
  <p class="label">Context — AGENTS.md</p>
@@ -108,7 +108,7 @@ details.ctx-section>.md{padding:0 0 16px}
108
108
  <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
109
109
  <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
110
110
  <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
111
- <p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
111
+ <p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
112
112
  npm run typecheck # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test # node:test — every test/*.test.ts
113
113
  npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
114
114
  npm run demo # end to end: all tools over stdio, then over stateless HTTP
package/docs/card.html CHANGED
@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
100
100
  <main class="card">
101
101
  <div class="top">
102
102
  <h1>mcp-context-card</h1>
103
- <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
103
+ <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
104
104
  </div>
105
105
  <section>
106
106
  <p class="label">Context — AGENTS.md</p>
@@ -108,7 +108,7 @@ details.ctx-section>.md{padding:0 0 16px}
108
108
  <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
109
109
  <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
110
110
  <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
111
- <p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
111
+ <p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
112
112
  npm run typecheck # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test # node:test — every test/*.test.ts
113
113
  npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
114
114
  npm run demo # end to end: all tools over stdio, then over stateless HTTP
package/docs/img/card-dark.png CHANGED
Binary file
package/docs/img/card-identity.png CHANGED
Binary file
package/docs/img/card-light.png CHANGED
Binary file
package/docs/index.html CHANGED
@@ -100,7 +100,7 @@ details.ctx-section>.md{padding:0 0 16px}
100
100
  <main class="card">
101
101
  <div class="top">
102
102
  <h1>mcp-context-card</h1>
103
- <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.0</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
103
+ <div class="pills"><span class="pill">io.github.Wolfe-Jam</span><span class="pill">v1.1.1</span><span class="pill accent">published</span><span class="pill">MIT</span></div>
104
104
  </div>
105
105
  <section>
106
106
  <p class="label">Context — AGENTS.md</p>
@@ -108,7 +108,7 @@ details.ctx-section>.md{padding:0 0 16px}
108
108
  <div class="ctx-preamble md"><p><code>mcp-context-card</code> is the essential MCP server for a project's <strong>context</strong> (this file), <strong>memory</strong>, and <strong>identity</strong> — usable as your base MCP, or dropped into any existing MCP server as an extension. Discoverable to any MCP client through the two surfaces already in the ecosystem: the Server Card <code>_meta</code> block and <code>ai-catalog.json</code> sibling entries.</p>
109
109
  <p><code>read_agents_md</code> serves this file, section by section, over the same MCP connection.</p></div>
110
110
  <div class="ctx-body"><details class="ctx-section" id="setup"><summary>Setup</summary><div class="md"><pre><code class="language-bash">npm ci</code></pre>
111
- <p>Node 22 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
111
+ <p>Node 20 or newer. No other system dependencies.</p></div></details><details class="ctx-section" id="build"><summary>Build</summary><div class="md"><pre><code class="language-bash">npm run build # tsc -p tsconfig.build.json → dist/
112
112
  npm run typecheck # tsc --noEmit over src/ + test/</code></pre></div></details><details class="ctx-section" id="test"><summary>Test</summary><div class="md"><pre><code class="language-bash">npm test # node:test — every test/*.test.ts
113
113
  npm run test:coverage # + the coverage gate (lines 90 / funcs 85 / branches 80, src/ only)
114
114
  npm run demo # end to end: all tools over stdio, then over stateless HTTP
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-context-card",
3
- "version": "1.1.0",
3
+ "version": "1.1.1",
4
4
  "mcpName": "io.github.Wolfe-Jam/mcp-context-card",
5
5
  "description": "The essential MCP components for a project's context (AGENTS.md), cross-session memory, and identity — a base MCP on its own, or a drop-in extension for any existing MCP server. Discoverable through the Server Card _meta block and ai-catalog.json sibling entries.",
6
6
  "keywords": [
package/server.json CHANGED
@@ -3,7 +3,7 @@
3
3
  "name": "io.github.Wolfe-Jam/mcp-context-card",
4
4
  "title": "mcp-context-card",
5
5
  "description": "MCP server for a project's context (AGENTS.md), memory, and identity — base or drop-in extension.",
6
- "version": "1.1.0",
6
+ "version": "1.1.1",
7
7
  "repository": {
8
8
  "url": "https://github.com/Wolfe-Jam/mcp-context-card",
9
9
  "source": "github"
@@ -13,7 +13,7 @@
13
13
  "registryType": "npm",
14
14
  "registryBaseUrl": "https://registry.npmjs.org",
15
15
  "identifier": "mcp-context-card",
16
- "version": "1.1.0",
16
+ "version": "1.1.1",
17
17
  "runtimeHint": "npx",
18
18
  "transport": {
19
19
  "type": "stdio"