@execufunction/mcp-server 0.2.0

package/README.md

@@ -0,0 +1,182 @@
+# ExecuFunction MCP Server
+
+A [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes ExecuFunction tools to IDE clients like Cursor, Claude Desktop, and VS Code.
+
+## Quick Start
+
+### 1. Create a Personal Access Token
+
+1. Go to ExecuFunction → Settings → Developer → Access Tokens
+2. Click "Create Token"
+3. Name it (e.g., "Cursor MCP")
+4. Select scopes: `mcp:*` (or specific scopes like `projects:read`, `tasks:write`)
+5. **Save the token immediately** - it's only shown once!
+
+### 2. Configure Your MCP Client
+
+#### Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "execufunction": {
+      "command": "npx",
+      "args": ["@execufunction/mcp-server"],
+      "env": {
+        "EXF_API_URL": "https://execufunction.com",
+        "EXF_PAT": "exf_pat_your_token_here"
+      }
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "execufunction": {
+    "command": "npx",
+    "args": ["@execufunction/mcp-server"],
+    "env": {
+      "EXF_API_URL": "https://execufunction.com",
+      "EXF_PAT": "exf_pat_your_token_here"
+    }
+  }
+}
+```
+
+#### VS Code
+
+Configure in your MCP extension settings.
+
+### 3. Restart Your IDE
+
+After configuration, restart your IDE to load the MCP server.
+
+## Available Tools
+
+### Projects
+| Tool | Description |
+|------|-------------|
+| `project_list` | List all projects with status filtering |
+| `project_get_context` | Get full project context (tasks, notes, signals) |
+
+### Tasks
+| Tool | Description |
+|------|-------------|
+| `task_list` | List tasks with project/status filters |
+| `task_create` | Create a new task |
+| `task_complete` | Mark a task as complete |
+
+### Knowledge / Notes
+| Tool | Description |
+|------|-------------|
+| `note_search` | Search knowledge base |
+| `note_create` | Create a new note |
+
+### People
+| Tool | Description |
+|------|-------------|
+| `people_search` | Search contacts |
+
+### Calendar
+| Tool | Description |
+|------|-------------|
+| `calendar_list_events` | List calendar events for a date range |
+| `calendar_create_event` | Create a new calendar event |
+
+### Codebase Indexing
+| Tool | Description |
+|------|-------------|
+| `codebase_list` | List indexed repositories |
+| `codebase_register` | Register a new repository for indexing |
+| `codebase_status` | Check indexing status and stats |
+| `codebase_index` | Index/re-index a repository (reads local files) |
+| `codebase_search` | Semantic search across indexed code |
+
+### Code Memories
+| Tool | Description |
+|------|-------------|
+| `code_memory_store` | Store a fact about the codebase |
+| `code_memory_search` | Search stored code facts |
+| `code_memory_list` | List all stored code memories |
+| `code_memory_delete` | Delete a code memory |
+
+## Resources
+
+The server also exposes project context bundles as MCP resources:
+
+- `exf://projects/{id}/context` - Full context bundle for a project
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `EXF_API_URL` | Yes | ExecuFunction API URL |
+| `EXF_PAT` | Yes | Personal Access Token |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Run in development mode
+npm run dev
+
+# Test with MCP Inspector
+npm run inspect
+
+# Build for production
+npm run build
+```
+
+## Security
+
+- PATs are stored as SHA-256 hashes - plaintext is never stored
+- Tokens can be revoked at any time from ExecuFunction Settings
+- Use minimal scopes for your use case
+- Never commit tokens to version control
+
+## Scopes
+
+| Scope | Description |
+|-------|-------------|
+| `mcp:*` | All MCP operations (recommended for IDE use) |
+| `projects:read` | Read project data |
+| `projects:write` | Create/update projects |
+| `tasks:read` | Read tasks |
+| `tasks:write` | Create/update/complete tasks |
+| `knowledge:read` | Search/read notes |
+| `knowledge:write` | Create notes |
+| `calendar:read` | View calendar/free slots |
+| `calendar:write` | Create calendar events |
+| `people:read` | Search/view contacts |
+| `people:write` | Create/update contacts |
+
+## Troubleshooting
+
+### "EXF_API_URL environment variable is required"
+
+Make sure you've configured the `env` section in your MCP client config.
+
+### "Invalid token"
+
+1. Check that your token starts with `exf_pat_`
+2. Verify the token hasn't been revoked
+3. Check the token hasn't expired
+
+### Tools not appearing
+
+1. Restart your IDE after configuration changes
+2. Check IDE logs for MCP errors
+3. Try running `npm run inspect` to test the server directly
+
+## License
+
+MIT