Registry /
llm-agents / targetprocess-mcp-server
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
startServer
✓ // This package is a server, not a library for direct import. Run it as a process.
The `targetprocess-mcp-server` package is designed to be run as a standalone server, exposing an MCP endpoint for AI agents. It does not export JavaScript/TypeScript symbols for direct library-style import into other applications for client-side consumption. The primary interaction model is by running the server as a process and then having AI agents communicate with its exposed MCP API. Programmatic startup, if supported internally, would be an advanced use case not typically exposed for direct import by consumers of the package.
TargetprocessClient
✓ // This package's internal components are not exposed for direct import by external applications.
While the server internally interacts with the Targetprocess API, the `TargetprocessClient` (or similar internal components responsible for API communication) is not exported for direct import and use by external applications. This package acts as the server-side intermediary, and its internal logic is encapsulated. External applications should interact with the MCP server itself, not its internal Targetprocess client.
ToolRegistry
✓ // Access to tools is via the running MCP server's API, not direct JS/TS import.
The various Targetprocess tools (e.g., `create_bug`, `get_release_user_stories`) are exposed by the running MCP server for AI agents to discover and invoke via the MCP protocol. There is no direct JavaScript/TypeScript export of a `ToolRegistry` or individual tool functions from this package for client-side import. Agents interact with the server's API to utilize these tools.
This quickstart demonstrates how to programmatically start the Targetprocess MCP Server as a child process, configuring it with necessary environment variables for connecting to your Targetprocess instance. It outlines the essential setup for a functional server instance that AI agents can then connect to and utilize.
import { exec } from 'node:child_process';
import path from 'node:path';
// IMPORTANT: Replace with your actual values or set as environment variables
// Generate an Access Token in Targetprocess: Settings -> Authentication and Security -> New Access Token
const TP_TOKEN = process.env.TP_TOKEN ?? 'YOUR_TP_TOKEN';
// Your Targetprocess API endpoint, e.g., 'https://your-instance.tpondemand.com'
const TP_BASE_URL = process.env.TP_BASE_URL ?? 'https://your-instance.tpondemand.com';
// Your Targetprocess User ID, typically found in your Targetprocess profile
const TP_OWNER_ID = process.env.TP_OWNER_ID ?? 'YOUR_TP_OWNER_ID';
if (!TP_TOKEN || !TP_BASE_URL || !TP_OWNER_ID) {
console.error('ERROR: Environment variables TP_TOKEN, TP_BASE_URL, and TP_OWNER_ID must be set.');
console.error('Please configure these either directly in this script or as system environment variables.');
process.exit(1);
}
// Determine the path to the server's executable script.
// In a typical npm install, this might be in node_modules/targetprocess-mcp-server/build/index.js (after a build step)
// For local development from a repository, it's often the main script in the root.
// This example assumes it's within a local node_modules structure or a directly cloned repo.
const serverScriptPath = path.resolve(process.cwd(), './node_modules/targetprocess-mcp-server/build/index.js'); // Common for installed packages
// Alternatively, if running directly from a cloned repo for development:
// const serverScriptPath = path.resolve(process.cwd(), './index.js'); // Adjust based on actual project structure
const command = `node ${serverScriptPath}`;
const options = {
env: {
...process.env,
TP_TOKEN,
TP_BASE_URL,
TP_OWNER_ID
}
};
console.log(`Attempting to start Targetprocess MCP Server with command: ${command}`);
const serverProcess = exec(command, options, (error, stdout, stderr) => {
if (error) {
console.error(`Server failed to start: ${error.message}`);
return;
}
if (stderr) {
console.error(`Server stderr: ${stderr}`);
}
console.log(`Server stdout: ${stdout}`);
});
serverProcess.stdout.on('data', (data) => {
console.log(`[MCP Server] stdout: ${data}`);
});
serverProcess.stderr.on('data', (data) => {
console.error(`[MCP Server] stderr: ${data}`);
});
serverProcess.on('close', (code) => {
console.log(`Targetprocess MCP Server process exited with code ${code}`);
});
console.log('Targetprocess MCP Server initiated. Check console for startup logs.');
console.log('You will need an MCP client (e.g., LobeHub, Claude) to interact with the running server.');
Debug
Known issues
breakingThe server explicitly requires Node.js version 20 or higher. Running with older Node.js versions will likely lead to startup failures or unexpected behavior.fixEnsure your Node.js environment is updated to version 20.x or newer. Use `nvm use 20` or install the latest LTS version.
affects: <2.0.0 (upgrade to 20.x)
gotchaCorrect configuration of `TP_TOKEN`, `TP_BASE_URL`, and `TP_OWNER_ID` environment variables is critical for server operation. Incorrect values will prevent connection to Targetprocess or result in unauthorized errors.fixVerify that `TP_TOKEN` is a valid Targetprocess Access Token with necessary permissions, `TP_BASE_URL` is the correct API endpoint (e.g., `https://your-instance.tpondemand.com`), and `TP_OWNER_ID` is your user ID in Targetprocess. Generate new tokens if necessary.
affects: >=1.0.0
gotchaThe server is designed for the Model Context Protocol (MCP). Attempting to interact with it via a standard REST API client or without an MCP-compatible agent will not work as intended, as it expects specific JSON-RPC 2.0 formatted messages.fixEnsure you are using an MCP-compatible client or AI agent (e.g., LobeHub, Claude MCP AI) to interact with the server. Understand the JSON-RPC 2.0 message structure required by MCP.
affects: >=1.0.0
gotchaComplex Targetprocess API queries using `WHERE` clauses with `IN` operators or `Count`-based filtering might not be fully supported by the underlying Targetprocess API via the server, leading to parsing errors.fixSimplify complex queries. If encountering 'Error during parameters parsing' or similar, try breaking down complex filters into multiple steps or using alternative query methods. Refer to Targetprocess API documentation for supported query structures.
affects: >=1.0.0
Errors
Common errors & fixes
ERROR: Environment variables TP_TOKEN, TP_BASE_URL, and TP_OWNER_ID must be set.
The server failed to start because one or more required environment variables for Targetprocess API connection were missing.
fixSet `TP_TOKEN`, `TP_BASE_URL`, and `TP_OWNER_ID` in your environment or in the script that launches the server. Example: `export TP_TOKEN="your_token" && export TP_BASE_URL="https://your-instance.tpondemand.com" && node build/index.js`.
Failed to connect to Targetprocess API: Unauthorized (401)
The provided `TP_TOKEN` is invalid, expired, or lacks the necessary permissions to access the Targetprocess API.
fixVerify your `TP_TOKEN` in Targetprocess settings. Generate a new Access Token if necessary and ensure it has the appropriate read/write permissions for the entities the server intends to manage. Also, check the `TP_BASE_URL` format.
MCP error -32600: Search failed: Failed to search UserStorys after 3 attempts: search UserStorys failed: 400 - Error during parameters parsing.
An AI agent issued a tool command with a query that the Targetprocess API could not parse, often due to overly complex `WHERE` clauses or unsupported filter patterns.
fixAdjust the AI agent's prompt or the tool's implementation to generate simpler and more direct Targetprocess API queries. Avoid highly complex `WHERE` clauses, especially with multiple `IN` operators.
Connection refused errors. Server disconnected messages. Command not found errors.
The MCP host client (e.g., AI agent) cannot connect to the running MCP server, or the server failed to start properly.
fixVerify the server process is running and listening on the expected port. Check firewall rules. Ensure the `command` and `args` in your MCP client configuration correctly point to the server's executable script. Review server logs for startup errors.
Audit
Dependencies
No dependency data recorded yet.