jt-mcp-server

Personal Model Context Protocol server that gives AI agents dev workflow tools — GitHub project management, conventional commits, static file serving, nvm-aware command execution, visual regression testing, Jira/Confluence integration, and more.

Quick Start

npx @houkasaurusrex/jt-mcp-server

Add to Claude Code

In your project's .claude/settings.json:

{
  "mcpServers": {
    "jt-mcp": {
      "command": "npx",
      "args": ["-y", "@houkasaurusrex/jt-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "NETLIFY_AUTH_TOKEN": "${NETLIFY_AUTH_TOKEN}",
        "ATLASSIAN_DOMAIN": "${ATLASSIAN_DOMAIN}",
        "ATLASSIAN_EMAIL": "${ATLASSIAN_EMAIL}",
        "ATLASSIAN_API_TOKEN": "${ATLASSIAN_API_TOKEN}"
      }
    }
  }
}

Tools

Dev Workflow

Tool	Description
dev_serve	Serve a directory on a port. Kills existing process on that port, starts serve -s, waits for 200 response, returns URL.
dev_serve_stop	Stop a dev server by port.
dev_run	Run a shell command with optional nvm Node version, working directory, and env vars. Resolves Node binary directly from ~/.nvm/versions/node/.
dev_port	Port management — check what's using a port, kill process on a port, wait_ready until a port accepts connections.
dev_worktree	Git worktree lifecycle — create (checkout + install deps), build (run build command), remove (clean up). Worktrees live at .claude/worktrees/<branch>/.
dev_install	Install project dependencies using the correct package manager (auto-detected from lockfile). Supports frozen/immutable lockfile mode for CI.
dev_script	Run a package.json script by name with the correct package manager. Validates the script exists and lists available scripts on error.
dev_deps	Add or remove npm packages using the correct package manager. Supports devDependencies.
dev_visual_regression	Orchestrate a full Playwright visual regression cycle: serve reference dir, capture baselines, serve test dir, run comparison, return results.

Search & Exploration

Tool	Description
dev_grep	Search file contents for patterns (regex or literal) with context lines, glob filtering. Respects .gitignore. Uses ripgrep.
dev_find	Find files/directories by glob pattern. Respects .gitignore. Uses fd with git ls-files fallback.
dev_read	Read file contents with line numbers, optional line ranges, binary detection, and path traversal protection.
dev_tree	Display directory tree structure. Skips node_modules, .git, build artifacts, and other common noise.

GitHub

Tool	Description
github_project_next_issue	Get the oldest "Todo" issue from a GitHub ProjectV2 board.
github_project_set_status	Update a project item's status (Todo / In Progress / Done).
github_project_complete_issue	Close a GitHub issue and set its project board status to Done in one call.
github_create_pr	Create a pull request via gh CLI.

Git

Tool	Description
git_conventional_commit	Stage files and create a conventional commit. Validates message format, refuses to stage .env or node_modules.

Jira (via acli CLI)

Requires the Atlassian CLI — run acli auth login once to authenticate.

Tool	Description
jira_search	Search issues with JQL, configurable fields and result limits.
jira_get_issue	Get full details of an issue by key.
jira_create_issue	Create issues (Task, Bug, Story, Epic) with description, assignee, labels, parent.
jira_transition	Transition issue status (e.g. "In Progress", "Done").
jira_add_comment	Add a comment to an issue.
jira_assign	Assign (user@email, @me) or unassign an issue.

Confluence (REST API)

Requires ATLASSIAN_DOMAIN, ATLASSIAN_EMAIL, and ATLASSIAN_API_TOKEN env vars.

Tool	Description
confluence_search	Search pages with CQL, returns IDs, titles, spaces, excerpts.
confluence_get_page	Read page content (storage XHTML, rendered HTML, or ADF).
confluence_create_page	Create a page in a space, optional parent for child pages.
confluence_update_page	Update page body/title with auto-incremented version.

Shell

Tool	Description
shell_lint	Run ShellCheck on shell scripts. Returns structured JSON findings with file, line, level, and message.

Netlify

Tool	Description
netlify_deploy_status	Check the latest deploy status for a Netlify site.
netlify_build_log	Get build/deploy logs (last N lines) for diagnosing failed deploys and CI issues.
netlify_function_log	Stream recent serverless function invocation logs for debugging.
netlify_list_deploys	List recent deploys with status, branch, context, and error info.
netlify_list_functions	List all deployed serverless functions for a site.

Memory (Knowledge Graph)

Tool	Description
memory_add_entities	Create entities (preferences, tools, projects, conventions) with a name, type, and observations.
memory_add_relations	Create typed directed relations between entities (e.g. PREFERS, USES, AVOIDS).
memory_add_observations	Add facts or notes to an existing entity.
memory_query	Search and traverse the knowledge graph by name, type, or relation.
memory_delete	Delete entities (cascades), relations, or observations.
memory_export	Export the entire graph as JSON.
memory_import	Import a graph from JSON (merge or replace).
memory_track_action	Track a repeatable action (build, test, deploy, lint) for pattern detection.
memory_suggest_tools	Analyze tracked actions to find patterns that could become new MCP tools.

Using the Memory Database

The memory tools provide a persistent knowledge graph that agents can use to remember user preferences, project conventions, and facts across sessions. Data is stored in a SQLite database at ~/.jt-memory/memory.db and auto-exported to ~/.jt-memory/memory.json on every write.

Enabling memory in a project

Add the following to your project's CLAUDE.md so the agent knows to use memory at the start of each session:

## Memory

This project uses `@houkasaurusrex/jt-mcp-server` memory tools. At the start of every session:
1. Call `memory_query` with no filters to load all stored context
2. Use the returned entities, observations, and relations to inform your work
3. When you learn new user preferences or project conventions, store them with `memory_add_entities` and `memory_add_observations`

How it works

• Entities have a name, type, and observations (facts). Types include preference, convention, project, tool, workflow, etc.
• Relations are directed edges between entities (e.g. JT --PREFERS--> Yarn Berry).
• Observations are string facts attached to an entity (e.g. "Always uses single-line conventional commits").
• The database persists at ~/.jt-memory/memory.db across all projects and sessions.
• Every write auto-exports to ~/.jt-memory/memory.json as a human-readable backup.
• Override paths with JT_MEMORY_DB and JT_MEMORY_EXPORT_PATH env vars.

Action tracking

The memory system can track repeatable actions agents perform across projects and suggest when patterns should become dedicated MCP tools.

Tracking an action:

{ "command": "yarn lint --fix", "description": "Auto-fix lint issues", "project": "my-app", "tags": ["lint", "fix"], "category": "lint" }

Checking for tool suggestions:

{ "min_occurrences": 3, "min_projects": 2 }

Returns exact command matches and tag-based clusters that exceed the thresholds, with suggestions for which patterns are good candidates for new tools.

Add the following to your project's CLAUDE.md to enable action tracking:

### Action Tracking

When performing substantive, repeatable actions (build, test, deploy, lint, format, git workflow),
call `memory_track_action` with command, description, project, tags, and category.
Do NOT track trivial commands (ls, cd, file reads, one-off searches).

Periodically call `memory_suggest_tools` to discover patterns worth converting to MCP tools.

Example: storing a preference

{ "entities": [{ "name": "commits", "type": "convention", "observations": ["Single-line conventional commits", "No Co-Authored-By trailers"] }] }

Example: querying at session start

{}                                // returns all entities
{ "type": "preference" }         // returns only preferences
{ "name": "yarn", "depth": 2 }   // traverse 2 levels from matching entities

Environment Variables

Variable	Required for
GITHUB_TOKEN	GitHub tools (PAT with repo + project scopes)
NETLIFY_AUTH_TOKEN	Netlify tools
ATLASSIAN_DOMAIN	Confluence tools (e.g. mycompany.atlassian.net)
ATLASSIAN_EMAIL	Confluence tools (account email)
ATLASSIAN_API_TOKEN	Confluence tools (create one)

Jira tools use the acli CLI which handles its own auth — run acli auth login once.

Development

yarn install
yarn build
yarn test
yarn test <pattern>   # e.g. yarn test dev-port

License

MIT