contextforge-mcp 0.1.76 → 0.1.78

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 (5) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +167 -91
  3. package/dist/index.js +61 -61
  4. package/dist/index.js.map +1 -1
  5. package/package.json +21 -5
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Alfredo Izquierdo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,26 +1,42 @@
1
- # ContextForge MCP Server
1
+ # ContextForge MCP — Persistent Memory for Claude, Cursor & Copilot
2
2
 
3
- Intelligent contextual memory system for AI-powered development. Store and retrieve knowledge across conversations, perfect for Claude Desktop and Claude Code.
3
+ [![npm version](https://img.shields.io/npm/v/contextforge-mcp.svg)](https://www.npmjs.com/package/contextforge-mcp)
4
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
5
+ [![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org)
6
+ [![Glama MCP](https://glama.ai/mcp/servers/alfredoizdev/contextforge-mcp/badges/score.svg)](https://glama.ai/mcp/servers/alfredoizdev/contextforge-mcp)
7
+
8
+ > Give Claude Code, Cursor, and GitHub Copilot **persistent memory across sessions** via the Model Context Protocol (MCP). Stop re-explaining your project every time.
9
+
10
+ ContextForge MCP is an open-source MCP server that connects your AI coding assistants to **long-term, searchable memory**. Decisions, architecture notes, debugging context, and project knowledge stay available across every session — across every tool that supports MCP.
11
+
12
+ - 🧠 **Persistent memory** — your AI remembers everything across sessions, days, and weeks
13
+ - 🔍 **Semantic search** — find knowledge by meaning, not keywords
14
+ - 🔗 **One memory, every tool** — Claude Code, Cursor, Copilot, Claude Desktop, Windsurf
15
+ - 🐙 **Git integration** — sync commits and PRs automatically
16
+ - ✅ **Task tracking** — issues, assignments, and project status
17
+ - 👥 **Team collaboration** — share projects and memory with your team
18
+ - 🆓 **Free tier** — get started without a credit card
19
+
20
+ ---
4
21
 
5
22
  ## Quick Start
6
23
 
7
- ### Installation
24
+ ### 1. Install
8
25
 
9
26
  ```bash
10
27
  npm install -g contextforge-mcp
11
28
  ```
12
29
 
13
- ### Get Your API Key
30
+ ### 2. Get your API key
14
31
 
15
32
  1. Go to **[contextforge.dev](https://contextforge.dev)**
16
- 2. Sign up for a free account
17
- 3. Navigate to Settings → API Keys
18
- 4. Click "Generate API Key"
19
- 5. Copy your key (starts with `cf_`)
33
+ 2. Sign up (free tier available)
34
+ 3. Settings → API Keys → **Generate API Key**
35
+ 4. Copy your key (starts with `cf_`)
20
36
 
21
- ### Configuration
37
+ ### 3. Connect to your AI tool
22
38
 
23
- #### For Claude Desktop
39
+ #### Claude Desktop
24
40
 
25
41
  Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
26
42
 
@@ -37,9 +53,9 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
37
53
  }
38
54
  ```
39
55
 
40
- **Restart Claude Desktop** and start using your memory!
56
+ Restart Claude Desktop.
41
57
 
42
- #### For Claude Code (CLI)
58
+ #### Claude Code (CLI)
43
59
 
44
60
  ```bash
45
61
  claude mcp add contextforge \
@@ -47,107 +63,131 @@ claude mcp add contextforge \
47
63
  -- contextforge-mcp
48
64
  ```
49
65
 
50
- Restart Claude Code and use `/mcp` to verify it's connected.
66
+ Restart Claude Code and run `/mcp` to verify it's connected.
67
+
68
+ #### Cursor
69
+
70
+ Add to your Cursor MCP settings:
71
+
72
+ ```json
73
+ {
74
+ "mcpServers": {
75
+ "contextforge": {
76
+ "command": "npx",
77
+ "args": ["contextforge-mcp"],
78
+ "env": {
79
+ "CONTEXTFORGE_API_KEY": "your-api-key-here"
80
+ }
81
+ }
82
+ }
83
+ }
84
+ ```
85
+
86
+ #### GitHub Copilot (VS Code)
87
+
88
+ Add to your Copilot MCP config:
89
+
90
+ ```json
91
+ {
92
+ "servers": {
93
+ "contextforge": {
94
+ "command": "npx",
95
+ "args": ["contextforge-mcp"],
96
+ "env": {
97
+ "CONTEXTFORGE_API_KEY": "your-api-key-here"
98
+ }
99
+ }
100
+ }
101
+ }
102
+ ```
51
103
 
52
104
  ---
53
105
 
54
106
  ## Available Tools
55
107
 
56
- ContextForge provides 3 types of functionality: **Knowledge Management**, **GitHub Integration**, and **Issue Tracking**.
108
+ ContextForge provides tools for **Knowledge Management**, **GitHub Integration**, **Issue Tracking**, and **Collaboration**.
57
109
 
58
110
  ### Knowledge Management
59
111
 
60
- Store, search, and organize your knowledge.
61
-
62
- | Tool | Description | Example |
63
- |------|-------------|---------|
64
- | `memory_ingest` | Save knowledge to memory | "Save this: our API uses JWT tokens" |
65
- | `memory_query` | Search your knowledge | "How do we handle authentication?" |
66
- | `memory_list_items` | List all stored items | "Show my saved items" |
67
- | `memory_delete` | Remove specific items | "Delete the item about old API" |
68
- | `memory_ingest_batch` | Save multiple items at once | "Save these 5 code snippets" |
69
- | `memory_delete_batch` | Delete items by filter | "Delete all items tagged 'draft'" |
112
+ | Tool | Description |
113
+ |------|-------------|
114
+ | `memory_ingest` | Save knowledge to memory |
115
+ | `memory_query` | Search your knowledge semantically |
116
+ | `memory_list_items` | List all stored items |
117
+ | `memory_delete` | Remove specific items |
118
+ | `memory_ingest_batch` | Save multiple items at once |
119
+ | `memory_delete_batch` | Delete items by filter |
70
120
 
71
121
  ### Spaces & Projects
72
122
 
73
- Organize your knowledge into workspaces.
74
-
75
- | Tool | Description | Example |
76
- |------|-------------|---------|
77
- | `memory_list_spaces` | List your spaces | "List my spaces" |
78
- | `memory_create_space` | Create a new space | "Create a space called Backend API" |
79
- | `memory_delete_space` | Delete a space | "Delete the old-project space" |
80
- | `memory_move_space` | Move space to project | "Move API space to Mobile project" |
81
- | `memory_list_projects` | List your projects | "Show my projects" |
82
- | `memory_create_project` | Create a new project | "Create project E-commerce App" |
83
- | `memory_delete_project` | Delete a project | "Delete the test project" |
84
- | `memory_link_project` | Link directory to project | "Link this folder to my project" |
85
- | `memory_unlink_project` | Unlink directory | "Unlink this folder" |
86
- | `memory_current_project` | Show linked project | "What project is linked here?" |
123
+ | Tool | Description |
124
+ |------|-------------|
125
+ | `memory_list_spaces` | List your spaces |
126
+ | `memory_create_space` | Create a new space |
127
+ | `memory_delete_space` | Delete a space |
128
+ | `memory_move_space` | Move space to project |
129
+ | `memory_list_projects` | List your projects |
130
+ | `memory_create_project` | Create a new project |
131
+ | `memory_delete_project` | Delete a project |
132
+ | `memory_link_project` | Link directory to project |
133
+ | `memory_unlink_project` | Unlink directory |
134
+ | `memory_current_project` | Show linked project |
87
135
 
88
136
  ### GitHub Integration
89
137
 
90
- Automatically sync commits and PRs from your repositories.
91
-
92
- | Tool | Description | Example |
93
- |------|-------------|---------|
94
- | `memory_git_connect` | Connect a GitHub repo | "Connect github.com/user/repo" |
95
- | `memory_git_list` | List connected repos | "Show my connected repos" |
96
- | `memory_git_activate` | Activate/deactivate webhook | "Activate the webhook" |
97
- | `memory_git_sync` | Import existing history | "Sync last 50 commits" |
98
- | `memory_git_commits` | List synced commits | "Show my recent commits" |
99
- | `memory_git_prs` | List synced PRs | "Show merged PRs this week" |
100
- | `memory_git_disconnect` | Disconnect a repo | "Disconnect the old repo" |
138
+ | Tool | Description |
139
+ |------|-------------|
140
+ | `memory_git_connect` | Connect a GitHub repo |
141
+ | `memory_git_list` | List connected repos |
142
+ | `memory_git_activate` | Activate/deactivate webhook |
143
+ | `memory_git_sync` | Import existing history |
144
+ | `memory_git_commits` | List synced commits |
145
+ | `memory_git_prs` | List synced PRs |
146
+ | `memory_git_disconnect` | Disconnect a repo |
101
147
 
102
148
  ### Issue Tracking
103
149
 
104
- Track tasks and collaborate with your team.
105
-
106
- | Tool | Description | Example |
107
- |------|-------------|---------|
108
- | `issues_list` | List your issues | "What's pending?" |
109
- | `issues_create` | Create a new issue | "Create issue: Fix login bug" |
110
- | `issues_start` | Mark as in progress | "Start working on abc123" |
111
- | `issues_resolve` | Mark as resolved | "Mark issue abc123 as done" |
112
- | `issues_resolve_by_name` | Resolve by title | "Resolve the login bug issue" |
113
- | `issues_assign` | Assign to collaborator | "Assign issue to john@example.com" |
114
- | `issues_what_next` | Get recommendation | "What should I work on next?" |
150
+ | Tool | Description |
151
+ |------|-------------|
152
+ | `issues_list` | List your issues |
153
+ | `issues_create` | Create a new issue |
154
+ | `issues_start` | Mark as in progress |
155
+ | `issues_resolve` | Mark as resolved |
156
+ | `issues_resolve_by_name` | Resolve by title |
157
+ | `issues_assign` | Assign to collaborator |
158
+ | `issues_what_next` | Get recommendation |
115
159
 
116
160
  ### Collaboration
117
161
 
118
- Share projects and work with your team.
119
-
120
- | Tool | Description | Example |
121
- |------|-------------|---------|
122
- | `project_share` | Share project by email | "Share project with alice@company.com" |
123
- | `collaborators_list` | List collaborators | "Who has access to this project?" |
162
+ | Tool | Description |
163
+ |------|-------------|
164
+ | `project_share` | Share project by email |
165
+ | `collaborators_list` | List collaborators |
124
166
 
125
167
  ### Snapshots & Export
126
168
 
127
- Backup and export your knowledge.
128
-
129
- | Tool | Description | Example |
130
- |------|-------------|---------|
131
- | `memory_snapshot_create` | Create a backup | "Create snapshot before refactoring" |
132
- | `memory_snapshot_list` | List all snapshots | "Show my backups" |
133
- | `memory_snapshot_restore` | Restore from backup | "Restore from yesterday's snapshot" |
134
- | `memory_snapshot_delete` | Delete a snapshot | "Delete old snapshot" |
135
- | `memory_export` | Export to JSON/MD/CSV | "Export my API space to markdown" |
136
- | `memory_import` | Import from file | "Import these notes" |
169
+ | Tool | Description |
170
+ |------|-------------|
171
+ | `memory_snapshot_create` | Create a backup |
172
+ | `memory_snapshot_list` | List all snapshots |
173
+ | `memory_snapshot_restore` | Restore from backup |
174
+ | `memory_snapshot_delete` | Delete a snapshot |
175
+ | `memory_export` | Export to JSON/MD/CSV |
176
+ | `memory_import` | Import from file |
137
177
 
138
178
  ### Utility
139
179
 
140
- | Tool | Description | Example |
141
- |------|-------------|---------|
142
- | `memory_stats` | View usage statistics | "Show my memory stats" |
143
- | `memory_relate` | Link two items | "Link these two items" |
144
- | `memory_help` | Show help | "How do I use ContextForge?" |
180
+ | Tool | Description |
181
+ |------|-------------|
182
+ | `memory_stats` | View usage statistics |
183
+ | `memory_relate` | Link two items |
184
+ | `memory_help` | Show help |
145
185
 
146
186
  ---
147
187
 
148
188
  ## Natural Language Examples
149
189
 
150
- You don't need to memorize commands. Just talk naturally:
190
+ You don't need to memorize commands — just talk naturally to your AI:
151
191
 
152
192
  ```
153
193
  # Knowledge
@@ -174,32 +214,68 @@ You don't need to memorize commands. Just talk naturally:
174
214
  | Variable | Required | Description |
175
215
  |----------|----------|-------------|
176
216
  | `CONTEXTFORGE_API_KEY` | Yes | Your API key from the dashboard |
217
+ | `CONTEXTFORGE_API_URL` | No | API endpoint (defaults to production) |
177
218
  | `CONTEXTFORGE_DEFAULT_SPACE` | No | Default space for operations |
178
219
 
179
220
  ---
180
221
 
222
+ ## How it works
223
+
224
+ ContextForge MCP is a thin client that translates Model Context Protocol tool calls into authenticated HTTP requests against the ContextForge API. Your knowledge is stored, indexed (semantic embeddings), and retrieved on the server side — the MCP client itself is stateless.
225
+
226
+ This means:
227
+ - **No infra to manage** — no local databases, no embeddings to run, no vector stores to maintain
228
+ - **Works everywhere your AI works** — same memory across Claude Code, Cursor, Copilot, etc.
229
+ - **Team collaboration** — shared projects sync in real time
230
+
231
+ ---
232
+
181
233
  ## Dashboard
182
234
 
183
- Manage your memories visually at **[contextforge.dev](https://contextforge.dev)**
235
+ Manage your memory visually at **[contextforge.dev](https://contextforge.dev)**:
184
236
 
185
237
  - View and organize your knowledge
186
238
  - Search and filter memories
187
- - Manage API keys
239
+ - Manage API keys and billing
188
240
  - Track issues and collaborate
189
241
  - Export and backup data
190
242
 
191
243
  ---
192
244
 
193
- ## Support
245
+ ## Development
194
246
 
195
- - [Documentation](https://contextforge.dev/docs)
196
- - [Report Issues](https://github.com/alfredoizdev/MCP-context-forge/issues)
197
- - Questions? Email: support@contextforge.app
247
+ ```bash
248
+ # Clone and install
249
+ git clone https://github.com/alfredoizdev/contextforge-mcp.git
250
+ cd contextforge-mcp
251
+ npm install
198
252
 
199
- ## License
253
+ # Build
254
+ npm run build
255
+
256
+ # Run tests
257
+ npm test
258
+
259
+ # Watch mode
260
+ npm run dev
261
+ ```
262
+
263
+ ---
264
+
265
+ ## Contributing
200
266
 
201
- MIT
267
+ Issues and pull requests are welcome at **[github.com/alfredoizdev/contextforge-mcp](https://github.com/alfredoizdev/contextforge-mcp)**.
202
268
 
203
269
  ---
204
270
 
205
- **Built with love by [Alfredo Izquierdo](https://github.com/alfredoizdev)**
271
+ ## Support
272
+
273
+ - 📖 [Documentation](https://contextforge.dev/docs)
274
+ - 🐛 [Report Issues](https://github.com/alfredoizdev/contextforge-mcp/issues)
275
+ - 💬 Questions: support@contextforge.app
276
+
277
+ ---
278
+
279
+ ## License
280
+
281
+ MIT © [Alfredo Izquierdo](https://github.com/alfredoizdev)